diff --git a/docs/docs/configure/permissions.md b/docs/docs/configure/permissions.md index 65bbc9393e..7263e8fb74 100644 --- a/docs/docs/configure/permissions.md +++ b/docs/docs/configure/permissions.md @@ -251,6 +251,12 @@ When prompted, you have three choices: "Allow always" approvals persist for your current session only. They reset when you restart Altimate Code. +### How SQL is classified for `sql_execute_write` + +`sql_execute` parses each query and asks for `sql_execute_write` only when a statement is not a read. Comments (except MySQL executable comments such as `/*! ... */`, which are refused), string literals, and column names such as `update_ts`, `t.update` or `s.t.update` do not count (dotted names still count on ClickHouse); a quoted, bracketed or spaced qualifier (`"t".update`, `t . update`) still asks. SQL the parser cannot read is treated as a write, so it is never run without write permission. On a dbt target, any Jinja (`{{ }}`, `{% %}`, `{# #}`) counts as a write too, even inside a comment or literal, because dbt renders and runs it first. + +When a query reaches the `sql_execute_write` check and a `"deny"` rule refuses it, the tool error tells the agent why the query counted as a write and what to change (hard-blocked statements such as `DROP DATABASE`, and writes inside a batch, fail earlier with their own messages): the statement that writes, the parser error and its position, or shell syntax such as `2>/dev/null` to remove. + ## Tips - **Start with `"ask"` and relax as you build confidence.** You can always approve patterns with "Allow always" during a session. diff --git a/docs/docs/usage/tool.md b/docs/docs/usage/tool.md index 7a1caea180..c61fddf72f 100644 --- a/docs/docs/usage/tool.md +++ b/docs/docs/usage/tool.md @@ -51,7 +51,7 @@ Only the data tools are exposed. Coding tools (`bash`, `read`, `edit`, ...), `db ## Permissions -Runs are read-only by default. Reads such as `sql_execute` on a SELECT and `schema_inspect` are allowed; anything else is refused with `Permission denied: . Re-run with --allow-write to enable writes.` Tools that change local configuration (`warehouse_add`, `warehouse_remove`, `warehouse_install_driver`) also need `--allow-write`. +Runs are read-only by default. Reads such as `sql_execute` on a SELECT and `schema_inspect` are allowed; anything else is refused with `Permission denied: . Re-run with --allow-write to enable writes.` For `sql_execute`, the refusal first says why the query counts as a write, so a malformed read can be fixed instead. Tools that change local configuration (`warehouse_add`, `warehouse_remove`, `warehouse_install_driver`) also need `--allow-write`. `DROP` of a database, schema, catalog or namespace (including `DROP EXTERNAL SCHEMA` and `DROP PLUGGABLE DATABASE`), `TRUNCATE`, and MySQL/MariaDB executable comments (`/*! ... */`, `/*M! ... */`) are refused even with `--allow-write` when the SQL check recognises them. The check reads the SQL text, so it is best effort: a statement the warehouse builds or decodes at run time (dynamic SQL assembled by concatenation, a stored routine, an unusual literal encoding) can get past it. For a hard guarantee, connect with a database user that has no `DROP` or `TRUNCATE` privilege. diff --git a/packages/opencode/src/altimate/mcp-server/workspace.ts b/packages/opencode/src/altimate/mcp-server/workspace.ts index fdd6bcf65b..8ad9111e3e 100644 --- a/packages/opencode/src/altimate/mcp-server/workspace.ts +++ b/packages/opencode/src/altimate/mcp-server/workspace.ts @@ -7,6 +7,7 @@ import * as WorkspaceClient from "../workspace/client" import { which, versionOf } from "../workspace/engine-probes" import { clearsFloor, engineEntry, ENGINE_BINARY } from "../workspace/engine-types" import { classifyAndCheck } from "../tools/sql-classify" +import { writeReason } from "../tools/read-only-sql" // Deliberately closed: adding a new engine capability requires classifying it. const METADATA_READS = new Set([ @@ -38,7 +39,7 @@ export function checkEngineRead(name: string, args: Record) { for (const query of queries) { const result = classifyAndCheck(query, dialect) if (result.parseError || result.blocked || result.queryType !== "read") { - throw new Error("Workspace SQL must be read-only. Use Altimate Code directly for writes.") + throw new Error("Workspace SQL must be read-only. Use Altimate Code directly for writes." + writeReason(query, dialect)) } } } diff --git a/packages/opencode/src/altimate/native/connections/data-diff.ts b/packages/opencode/src/altimate/native/connections/data-diff.ts index 22c8905141..df17f2725b 100644 --- a/packages/opencode/src/altimate/native/connections/data-diff.ts +++ b/packages/opencode/src/altimate/native/connections/data-diff.ts @@ -9,7 +9,7 @@ import type { DataDiffParams, DataDiffResult, PartitionDiffResult } from "../types" import * as Registry from "./registry" -import { requireReadOnlyQuery } from "../../tools/read-only-sql" +import { requireReadOnlyQuery, writeReason } from "../../tools/read-only-sql" import { classifyAndCheck } from "../../tools/sql-classify" // --------------------------------------------------------------------------- @@ -196,7 +196,7 @@ async function executeQuery(sql: string, warehouseName: string | undefined, meta const dialect = warehouseTypeToDialect(Registry.getConfig(warehouseName)?.type ?? "generic") if (metadata) { const check = classifyAndCheck(sql, dialect) - if (check.blocked || check.queryType !== "read") throw new Error("Data diff metadata must be read-only") + if (check.blocked || check.queryType !== "read") throw new Error(`Data diff metadata must be read-only.${writeReason(sql, dialect)}`) } else { requireReadOnlyQuery(sql, dialect) } @@ -900,8 +900,11 @@ export async function runDataDiff(params: DataDiffParams): Promise Registry.canonicalType(warehouse ? Registry.getConfig(warehouse)?.type : undefined) ?? undefined for (const [sql, warehouse] of [[args.source, sourceWarehouse], [args.target, targetWarehouse]] as const) if (classifyAndCheck(sql, dialectOf(warehouse)).blocked) - throw new Error("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety. This cannot be overridden.") + throw new Error(hardBlockRefusal("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.", sql, dialectOf(warehouse))) for (const side of sides) await ctx.ask({ permission: "sql_execute_read", diff --git a/packages/opencode/src/altimate/tools/read-only-sql.ts b/packages/opencode/src/altimate/tools/read-only-sql.ts index 7ce5fa345b..54ee0b148a 100644 --- a/packages/opencode/src/altimate/tools/read-only-sql.ts +++ b/packages/opencode/src/altimate/tools/read-only-sql.ts @@ -1,5 +1,5 @@ -import { classifyAndCheck, isSingleQuery } from "./sql-classify" -import { maskSql, tokenizeSql } from "./sql-tokenize" +import { UNAVAILABLE_NEXT_STEP, hardBlockCause, hasExecutableComment, classifyAndCheck, explainWrite, isSingleQuery, isSqlServerDialect } from "./sql-classify" +import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" import { sqlFunctionCalls } from "./sql-functions" import { hasSideEffectFunction } from "./sql-function-policy" @@ -8,58 +8,136 @@ import { hasSideEffectFunction } from "./sql-function-policy" * CTE or subquery it is placed in), it has no statement separator, and it calls no function * that writes or runs SQL (dynamic query() included). Undefined otherwise. */ function readOnlyBody(sql: string, dialect?: string): { masked: string; body: string } | undefined { + const checked = embeddable(sql, dialect) + return "refused" in checked ? undefined : checked +} + +/** readOnlyBody's checks, in order, with the first failed one named in fixed words (no SQL text). A write or + * hard block is refused without a reason: the classifier explains those. */ +function embeddable(sql: string, dialect?: string): { masked: string; body: string } | { refused: string } { const { queryType, blocked } = classifyAndCheck(sql, dialect) // Settled already; the function scan below is costly on deeply nested input. - if (blocked || queryType !== "read") return undefined + if (blocked || queryType !== "read") return { refused: "" } const { tokens, complete } = tokenizeSql(sql, dialect) const masked = maskSql(tokens) // All calls use real code '(' tokens. - const unsafeFunction = sqlFunctionCalls(sql, dialect).some( - (call) => call.escaped || call.name === "query" || hasSideEffectFunction(call.name), - ) + const calls = sqlFunctionCalls(sql, dialect) + // SQL Server's XML .query() takes XQuery, not SQL, as in the classifier; elsewhere query() runs SQL text. + if (!isSqlServerDialect(dialect) && calls.some((call) => call.name === "query")) { + return { refused: "it calls query(), which runs SQL text that cannot be checked; query the tables directly" } + } + if (calls.some((call) => call.escaped)) return { refused: "it has an escaped function call, which cannot be checked" } + if (calls.some((call) => hasSideEffectFunction(call.name))) { + return { refused: "it calls a function that is not known to be read-only" } + } const body = masked.trim().replace(/;$/, "").trim() + if (body.includes(";")) return { refused: "it holds more than one statement" } + if (!isSingleQuery(sql, dialect)) { + return { refused: "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" } + } let depth = 0 let balanced = true for (const char of body) { if (char === "(") depth++ if (char === ")" && --depth < 0) balanced = false } - const safe = - !blocked && - queryType === "read" && - isSingleQuery(sql, dialect) && - complete && - !unsafeFunction && - balanced && - depth === 0 && - !body.includes(";") - return safe ? { masked, body } : undefined + if (!complete || !balanced || depth !== 0) return { refused: "its parentheses, quotes or comments do not balance" } + return { masked, body } } /** Throws unless sql is one read-only query that is safe to embed in a larger query. */ -export function requireReadOnlyQuery(sql: string, dialect?: string): void { - if (readOnlyBody(sql, dialect) === undefined) - throw new Error("Only a single read-only query is accepted here; it never writes data.") +export function requireReadOnlyQuery(sql: string, dialect?: string, input?: string): void { + if (readOnlyBody(sql, dialect) !== undefined) return + // When the caller wrapped user input in SQL it built, name that input: a reason with positions or "it" would + // describe text the user never wrote. + if (input) throw new Error(`The ${input} must be part of a single read-only query; it never writes data.`) + throw new Error(`Only a single read-only query is accepted here; it never writes data.${writeReason(sql, dialect)}`) +} + +// Statement words refused anywhere in a read handed to sql_check. A column qualified by a whole +// identifier (t.update) is not one, as in the classifier, except on ClickHouse, whose bundled parser +// accepts trailing text. +const WORDS = "INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|COPY|ATTACH|DETACH|PRAGMA|VACUUM|CALL|DO|INTO|INSTALL|LOAD|EXPORT|IMPORT|GRANT|REVOKE" +const QUALIFIED = "(? pattern.test(body)) ) { throw new Error( - "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data.", + "This operation only accepts a single read-only SELECT (or WITH ... SELECT); it never writes or fixes data." + + (options.explain === false ? "" : writeReason(sql, dialect)), ) } const semicolon = checked.masked.indexOf(";") return semicolon < 0 ? sql : sql.slice(0, semicolon) + sql.slice(semicolon + 1) } + +/** Every hard-block refusal says this; its "permission" keyword sets the telemetry error class. */ +export const NOT_OVERRIDABLE = "This cannot be overridden by any permission rule." + +/** A hard-block refusal: head, then "cannot be overridden" unless only unreadable text (an open quote or comment) + * made a word count, then the reason. */ +export function hardBlockRefusal(head: string, sql: string, dialect?: string): string { + const unreadable = !tokenizeSql(sql, dialect).complete && !hasExecutableComment(sql, dialect) + return `${head}${unreadable ? "" : ` ${NOT_OVERRIDABLE}`}${writeReason(sql, dialect)}` +} + +/** Why sql is refused as a read, as a sentence to append to a refusal: a hard block, the classifier's reason for a write, + * a read shape that cannot be embedded, or a statement word refused by the stricter list. Empty for accepted reads. */ +export function writeReason(sql: string, dialect?: string): string { + const { queryType, blocked } = classifyAndCheck(sql, dialect) + if (blocked) { + // Name the first statement that is blocked on its own, by position only (no SQL text is quoted back). + const statements = tokenizeSql(sql, dialect).complete ? statementsOf(sql, dialect) : [] + const index = statements.length > 1 ? statements.findIndex((statement) => classifyAndCheck(statement, dialect).blocked) : -1 + const where = index >= 0 ? `statement ${index + 1} of ${statements.length} is` : "it holds" + const cause = hardBlockCause(index >= 0 ? statements[index] : sql, dialect) + const hard = ` It is refused because ${where} a hard-blocked statement (${cause}); hard-blocked statements never run, whatever the permission rules allow.` + // Text that cannot be read (an open or unsupported quote or comment) is blocked on its words alone, inside the + // unreadable text or outside it: name the unreadable text first, since fixing it may be the whole fix. + const untilClosed = + " Until it can be read, words such as DROP DATABASE or TRUNCATE anywhere in the SQL, inside that quoted text or" + + " outside it, count as a hard-blocked statement; a real one outside it stays refused once the text is fixed." + return tokenizeSql(sql, dialect).complete || hasExecutableComment(sql, dialect) + ? hard + : ` It counts as a write because ${explainWrite(sql, dialect).reason}.${untilClosed}` + } + if (queryType === "write") { + const { reason, unreadable, unavailable } = explainWrite(sql, dialect) + // A missing classifier is an installation failure, not a permission decision. + const head = unreadable || unavailable ? "It counts as a write because" : "It counts as a write, which needs a write permission this path does not have, because" + return ` ${head} ${reason}.${unavailable ? ` ${UNAVAILABLE_NEXT_STEP}` : ""}` + } + // Name the word only when it is the sole reason: the body is otherwise one SELECT or WITH query. + const checked = embeddable(sql, dialect) + const body = "refused" in checked ? undefined : checked.body + if (!body || !/^(SELECT|WITH)\b/i.test(body)) { + const cause = + "refused" in checked + ? checked.refused + : body!.startsWith("(") + ? "it starts with a parenthesis (for UNION or a similar set operation, move the parenthesized branches into a WITH query or drop their parentheses)" + : "it is not a SELECT or WITH query (a command such as SHOW cannot be embedded)" + return ` This read is invalid here because ${cause}; send a single SELECT or WITH query that can be embedded.` + } + const [statement, replace] = wordPatterns(dialect) + const word = (statement.exec(body) ?? replace.exec(body))?.[0] + return word ? ` It contains the statement word ${word.toUpperCase()} outside a literal or comment, so the read-only permission does not cover it; quote it if it is a column name${/^(snowflake|oracle)$/i.test(dialect ?? "") ? ", in uppercase as this engine stores unquoted names" : ""}.` : "" +} diff --git a/packages/opencode/src/altimate/tools/sql-classify.ts b/packages/opencode/src/altimate/tools/sql-classify.ts index a79357eb34..2df3ed78c3 100644 --- a/packages/opencode/src/altimate/tools/sql-classify.ts +++ b/packages/opencode/src/altimate/tools/sql-classify.ts @@ -88,7 +88,13 @@ function hasQueryWriteClause(sql: string, dialect?: string): boolean { let masked = maskSql(tokenizeSql(sql, dialect).tokens) // UNPIVOT's INTO NAME labels output columns; it does not create a table. if (dialect?.toLowerCase() === "duckdb") masked = maskUnpivotLabels(masked) - return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i.test(masked) + // A name qualified by a table or alias (t.update, s.delete) is a column, not a clause. The qualifier + // must be a whole unquoted identifier directly before the dot: `1. INTO t` and `0x1.INTO t` are a + // number followed by SELECT INTO, and anything else stays a write. The lookbehind runs only where a + // keyword matched, so long masked literals are not rescanned at every position. + // The bundled ClickHouse parser accepts trailing text it cannot read, so there every keyword counts. + if (dialect?.toLowerCase() === "clickhouse") return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i.test(masked) + return /\b(INTO|INSERT|UPDATE|DELETE|MERGE)\b(? kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text), - ) + if (hasExecutableComment(sql, dialect)) cause = "an executable comment" for (const stmt of statements) { - if (HARD_DENY_PATTERN.test(stmt)) blocked = true + const match = HARD_DENY_PATTERN.exec(stmt) + if (match) cause ??= hardDenyLabel(match[0]) } // When quoting or comments cannot be read with certainty, no reading of the literals or comments // can be trusted to hide a hard deny (a misread literal can make a real statement look like a @@ -193,7 +227,7 @@ function classifyFallback(sql: string, dialect?: string, write = true): { queryT const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { // Escapes decoded too: dynamic SQL may run a literal such as '\x44ROP SCHEMA s'. - if (mentionsHardDenyAnywhere(sql)) blocked = true + if (mentionsHardDenyAnywhere(sql)) cause ??= "hard-blocked words (such as DROP DATABASE or TRUNCATE) in text that cannot be fully read" } else { // Read with certainty: the statement words in code (literals and comments masked, each quoted // identifier a placeholder name, so DROP/**/SCHEMA reads as DROP SCHEMA) decide too, since T-SQL runs `SELECT 1 DROP DATABASE x` @@ -204,24 +238,32 @@ function classifyFallback(sql: string, dialect?: string, write = true): { queryT const chained = (/^snowflake$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && /(->>|\bASYNC\s*\(|:=\s*\(|\bDEFAULT\s*\()\s*TRUNCATE\b(?!\s*\()/i.test(names) - if (CODE_HARD_DENY.test(names) || handlerTruncate(names) || chained || (write && WRITE_TRUNCATE.test(names))) - blocked = true + const code = CODE_HARD_DENY.exec(names) + if (code) cause ??= hardDenyLabel(code[0]) + else if (handlerTruncate(names) || chained || (write && WRITE_TRUNCATE.test(names))) cause ??= "TRUNCATE" // Dynamic SQL runs its literals, joined into one statement ('DROP ' + 'DATABASE x', or PostgreSQL's // adjacent constants), whether the call reads as a read (SELECT exec('...')) or a write. This runs at // every nesting depth, as on main. Both readings count: quoted names masked to spaces, as on main, so // EXEC[sp_executesql] and PREPARE`p`FROM keep their word boundaries, and quoted names unwrapped, so // "exec"('...') and [exec]('...') count as calls. const dynamic = DYNAMIC_SQL.test(maskSql(lexical.tokens)) || DYNAMIC_SQL.test(maskSql(lexical.tokens, true)) - if (dynamic && mentionsHardDenyAnywhere(sql)) blocked = true + if (dynamic && mentionsHardDenyAnywhere(sql)) + cause ??= "dynamic SQL (EXEC, PREPARE or DO) with hard-blocked words (such as DROP DATABASE or TRUNCATE) in its text" } - return { queryType: "write", blocked } + return { queryType: "write", blocked: cause !== undefined, ...(cause && { cause }) } } -/** Where statements need no separator (T-SQL) or the dialect is not one the lexer models, a read +/** The statement keyword, if any. Where statements need no separator (T-SQL) or the dialect is not one the lexer models, a read * must hold no statement keyword in its code (literals, identifiers and comments masked): the * engine would run `SELECT ... DELETE FROM t` as two statements however a parser reads it. */ -function batchedStatement(masked: string, dialect?: string): boolean { - return (/^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && BATCH_STATEMENT.test(masked) +function batchedStatement(masked: string, dialect?: string): string | undefined { + if (!isSqlServerDialect(dialect) && isModeledDialect(dialect)) return undefined + // A name qualified by a whole unquoted identifier (t.update, s.t.into) cannot start a statement: + // every part after the first of a dotted name (s.t.update) is a name. + const names = masked.replace(/((?:^|[^\w$.])[A-Za-z_][\w$]*)((?:\.[A-Za-z_][\w$]*)+)/g, (_, head: string, rest: string) => + head + rest.replace(/[A-Za-z_][\w$]*/g, "_"), + ) + return BATCH_STATEMENT.exec(names)?.[0] } // T-SQL statements that can follow a read in the same batch. Words that are also common column names @@ -432,7 +474,7 @@ function functionSafety(sql: string, dialect: string | undefined, depth: number, Object.hasOwn(SQL_ARGUMENTS, call.name) && call.qualifier === undefined && !hasSideEffectFunction(call.name) if (depth > 0 && !nestedExecutor && !isReadOnlyNestedFunction(call.name, call.qualifier)) write = true // SQL Server's XML .query() takes XQuery, not executable SQL. - if (call.name === "query" && /^(sqlserver|tsql|mssql|fabric)$/i.test(dialect ?? "")) continue + if (call.name === "query" && isSqlServerDialect(dialect)) continue const argument = Object.hasOwn(SQL_ARGUMENTS, call.name) ? SQL_ARGUMENTS[call.name] : undefined if (!argument) continue const inner = sqlLiteral(call.args[argument.index], dialect) @@ -455,13 +497,16 @@ export function classifyAndCheck(sql: string, dialect?: string): { queryType: "read" | "write" blocked: boolean parseError?: string + /** Which hard-block rule matched, as a fixed label with no SQL text; set when blocked. */ + cause?: string } { const result = classifySql(sql, dialect, 0) if (result.queryType !== "write" || result.blocked) return result // A write may also run the SQL in its literals: a routine body created and called in the same call. Only // SQL read with certainty; otherwise the word scan of the whole text already covered its literals. const lexical = tokenizeSql(sql, dialect) - if (lexical.complete && quotedHardDeny(lexical.tokens, dialect)) return { ...result, blocked: true } + if (lexical.complete && quotedHardDeny(lexical.tokens, dialect)) + return { ...result, blocked: true, cause: "a string literal this write may run, holding a hard-blocked statement or a Unicode escape" } return result } @@ -476,29 +521,32 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { queryType: "read" | "write" blocked: boolean parseError?: string + cause?: string } { if (!sql || typeof sql !== "string") return { queryType: "read", blocked: false } const lexical = tokenizeSql(sql, dialect) if (!lexical.complete) { return { ...classifyFallback(sql, dialect), parseError: "SQL contains unterminated or unsupported quoted text or comments" } } - if (!getStatementTypes) return { ...classifyFallback(sql, dialect), parseError: "SQL parser is unavailable" } + if (!getStatementTypes) return { ...classifyFallback(sql, dialect), parseError: PARSER_UNAVAILABLE } try { const result = getStatementTypes(parserSql(sql, dialect), dialect) if (!Array.isArray(result?.statements) || result.statement_count !== result.statements.length) { - return { ...classifyFallback(sql, dialect), parseError: "SQL parser returned an invalid statement list" } + return { ...classifyFallback(sql, dialect), parseError: PARSER_INVALID_RESULT } } // A generic parser can treat MySQL arithmetic (--2) as a comment and omit // trailing statements. Keep dialect-aware lexical hard denies authoritative. const functions = functionSafety(sql, dialect, depth) const masked = maskSql(lexical.tokens) - const blocked = - functions.blocked || - classifyFallback(sql, dialect, false).blocked || - result.statements.some( - (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), - ) + const hardType = result.statements.find( + (s: { statement_type: string }) => s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()), + )?.statement_type + const cause = + (functions.blocked ? "SQL run from a string literal" : undefined) ?? + classifyFallback(sql, dialect, false).cause ?? + (hardType ? hardDenyLabel(hardType) : undefined) + const blocked = cause !== undefined const queryType = !functions.write && @@ -515,12 +563,253 @@ function classifySql(sql: string, dialect: string | undefined, depth: number): { otherIsReadOnly(sql, result.statements, dialect) ? "read" : "write" - return { queryType, blocked: blocked || (queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens))) } + // ClickHouse's bundled parser accepts trailing text, so a shell redirect to a descriptor or /dev/null + // (never SQL) would pass as a read. Treat such a read as unreadable so the residue is named, as on other + // dialects; a write is already refused and named by its type. + // A trailing pipe into a shell command with a flag counts too (never `||`, ClickHouse's concatenation). A file + // tail does not: `a > b.csv` compares a column there. + if ( + queryType === "read" && + dialect?.toLowerCase() === "clickhouse" && + (masked.search(SHELL_REDIRECT) >= 0 || CLICKHOUSE_PIPE_TAIL.test(masked.slice(-400))) + ) { + return { ...classifyFallback(sql, dialect), parseError: "shell redirect after the SQL" } + } + const writeTruncate = queryType === "write" && WRITE_TRUNCATE.test(namesKept(lexical.tokens)) + const finalCause = cause ?? (writeTruncate ? "TRUNCATE" : undefined) + return { queryType, blocked: finalCause !== undefined, ...(finalCause && { cause: finalCause }) } } catch (error) { return { ...classifyFallback(sql, dialect), parseError: error instanceof Error ? error.message : String(error) } } } +// Shell syntax pasted into a query out of terminal habit. A redirect to a descriptor or /dev/null +// (`2>/dev/null`, `2>&1`) can sit anywhere, even before LIMIT. At the very end there may also be one pipe +// into a shell command (`| head -20`) or one redirect into a file (`> out.csv`). A file target must start +// like a path (/, ./, ../, ~/) or end in a known output extension, so comparisons such as `x > 2`, +// `x > 1.5` and `x > t.total` never match. The tail patterns run on at most 400 characters and have no +// nested repetition. +const SHELL_REDIRECT = /\s(?:[12]|&)?>>?[ \t]*(?:&[12]|\/dev\/null)(?![\w/])/g +// ClickHouse parses `|` as an operator, so only a command with a flag argument (`| head -5`, `| wc -l`) counts: +// `a | head` may be an expression on a column named head. +const CLICKHOUSE_PIPE_TAIL = /(?>?[ \t]*(?:(?:\/|\.\.?\/|~\/)[\w./~-]*|[\w~-][\w~.-]*\.(?:csv|tsv|txt|json|jsonl|log|out|err|sql|parquet|tmp))[ \t]*$/i + +/** The shell syntax in a query that is a read without it, or undefined. Only code counts (literals and + * comments are masked), and only text that does not parse as sent. The query is never rewritten: the + * caller names the residue so the sender removes it, since running the query without it would run SQL + * other than what was sent. Fragments are named by their form (`2>/dev/null`, `> `, `| head ...`), + * since a path or a pipe's arguments may hold private text and telemetry records the error. */ +export function shellResidue(sql: string, dialect?: string): string | undefined { + const lexical = tokenizeSql(sql, dialect) + if (!lexical.complete || !classifyAndCheck(sql, dialect).parseError) return undefined + // Masking keeps every offset, so a span of the masked text cuts the same span of the original. + let masked = maskSql(lexical.tokens) + const cuts: Array<{ start: number; end: number; label: string }> = [] + for (const match of masked.matchAll(SHELL_REDIRECT)) { + cuts.push({ start: match.index!, end: match.index! + match[0].length, label: match[0].replace(/\s+/g, "") }) + } + // Only the last 400 characters can hold a tail; strip trailing ; and whitespace first. + // A backward loop, not a `$`-anchored regex: masked literals can be long runs of spaces, and a regex + // would retry the end-of-text match from every position in them. + let end = masked.length + while (end > 0 && /[\s;]/.test(masked[end - 1])) end-- + const offset = Math.max(0, end - 400) + const window = masked.slice(offset, end) + const pipe = SHELL_PIPE_TAIL.exec(window) + const file = pipe ? undefined : SHELL_FILE_TAIL.exec(window) + if (pipe) cuts.push({ start: offset + pipe.index, end: masked.length, label: `| ${pipe[1].toLowerCase()} ...` }) + if (file) cuts.push({ start: offset + file.index, end: masked.length, label: `${file[0].trim().match(/^[12&]?>>?/)![0]} ` }) + if (!cuts.length) return undefined + cuts.sort((a, b) => a.start - b.start) + const labels: string[] = [] + let query = "" + let position = 0 + for (const cut of cuts) { + if (cut.end <= position) continue + query += sql.slice(position, Math.max(cut.start, position)) + " " + labels.push(cut.label) + position = cut.end + } + query += sql.slice(position) + if (!query.trim()) return undefined + const result = classifyAndCheck(query, dialect) + return result.queryType === "read" && !result.blocked ? labels.join("`, `") : undefined +} + +/** What to do when the SQL classifier itself is unavailable: no rewrite of the SQL can help. */ +export const UNAVAILABLE_NEXT_STEP = "Changing the SQL will not help; ask the user to check the installation." + +// Whether the SQL holds an executable comment (a /*! comment) as a comment token, not inside a literal. +export function hasExecutableComment(sql: string, dialect?: string): boolean { + return tokenizeSql(sql, dialect).tokens.some(({ kind, text }) => kind === "comment" && /^\/\*(?:!|[mM]!)/.test(text)) +} + +// Which hard-block rule a blocked statement matched, as the classifier recorded it (no SQL text). +export function hardBlockCause(sql: string, dialect?: string): string { + return classifyAndCheck(sql, dialect).cause ?? "a hard-blocked statement" +} + +// Statement keywords that may name an UNKNOWN statement in a refusal. +const STATEMENT_KEYWORDS = new Set([ + "ATTACH", "DETACH", "INSTALL", "LOAD", "SET", "RESET", "PRAGMA", "COPY", "CALL", "EXEC", "EXECUTE", "GRANT", "REVOKE", + "VACUUM", "ANALYZE", "EXPORT", "IMPORT", "USE", "BEGIN", "COMMIT", "ROLLBACK", "CHECKPOINT", "OPTIMIZE", "SYSTEM", + "KILL", "RENAME", "COMMENT", "REFRESH", "UNLOAD", "PUT", "GET", "REMOVE", "LIST", +]) + +/** The parser's position and the kind of error only: everything from the first quoted or named token + * (`got`, `found`, `near`, a parenthesis, a quote, a colon after the kind) is cut, since telemetry records + * this error and its masking does not cover every token the parser prints. */ +function parserMessage(message: string): string { + const located = /^(.*?line \d+, column \d+:\s*)([\s\S]*)$/.exec(message) + const prefix = located ? located[1] : "" + const detail = (located ? located[2] : message) + .split(/\s+(?:got|found|near)\b|\s*[('"`[:]/i)[0] + .replace(/[\s,;:]+$/, "") + return `${prefix}${detail}`.trim() || "parse error" +} + +function batchKeywordExplanation(dialect?: string): string { + return isSqlServerDialect(dialect) + ? "SQL Server runs a statement there even without a separator" + : "this dialect is not modeled, so it may run as a statement" +} + +/** + * Why classifyAndCheck treats this SQL as a write, in words an agent can act on: shell residue to + * remove, the parser error and its position, or the first statement that is not a read. `unreadable` + * is true when the SQL could not be read at all (fix the text), false when a statement writes. + */ +export function explainWrite( + sql: string, + dialect?: string, +): { reason: string; unreadable: boolean; unavailable?: boolean; residue?: boolean } { + const unreadable = (reason: string) => ({ reason, unreadable: true }) + const writes = (reason: string) => ({ reason, unreadable: false }) + const residue = shellResidue(sql, dialect) + if (residue) { + return { ...unreadable(`it contains shell syntax (\`${residue}\`), which is not SQL. Remove it and send only the SQL`), residue: true } + } + const lexical = tokenizeSql(sql, dialect) + if (!lexical.complete) { + // An executable comment (/*! ... */) is closed but runs as SQL on some engines, so it is never read as one. + if (hasExecutableComment(sql, dialect)) { + return unreadable("it contains an executable comment (/*! ... */), which some engines run as SQL; remove it or use a plain comment") + } + return unreadable( + "it has unterminated or unsupported quoted text or comments, so it cannot be proven read-only. To fix the syntax, check that every " + + "quote and comment is closed; inside a string literal, write a single quote as ''" + ) + } + const statements = statementsOf(sql, dialect) + for (const [index, statement] of statements.entries()) { + const result = classifySql(statement, dialect, 0) + if (result.queryType === "read" && !result.blocked) continue + // Statements are not quoted back, since telemetry records this error; the parser's own message + // quotes at most a token, which telemetry masks as a literal. + const where = statements.length > 1 ? `statement ${index + 1} of ${statements.length}` : "it" + // Where statements need no separator, a statement keyword is the real reason, even if it breaks the parse. + const batchKeyword = batchedStatement(maskSql(tokenizeSql(statement, dialect).tokens), dialect) + // The classifier itself could not run: no rewrite of the SQL can help. + if (result.parseError === PARSER_UNAVAILABLE || result.parseError === PARSER_INVALID_RESULT) { + return { + reason: "the SQL classifier is unavailable in this installation, so no query can be proven read-only", + unreadable: false, + unavailable: true, + } + } + if (result.parseError && batchKeyword) { + return writes( + `${where} holds the statement keyword ${batchKeyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + + `${batchKeywordExplanation(dialect)}` + + "; run each statement in its own call, or quote it if it is a column name", + ) + } + // A SELECT ... INTO the parser cannot read (MySQL INTO OUTFILE or @var) is still a write: say so, not "fix the syntax". + const code = maskSql(tokenizeSql(statement, dialect).tokens) + if (result.parseError && /^\s*(SELECT|WITH)\b/i.test(code) && /\bINTO\b/i.test(code) && hasQueryWriteClause(statement, dialect)) { + return writes(`${where} has a write clause, such as SELECT ... INTO a table, file or variable; remove it to read`) + } + if (result.parseError) { + return unreadable( + `the ${dialect ?? "generic"} SQL parser could not read ${where} (${parserMessage(result.parseError)}), so it cannot be proven read-only. ` + + "The position is approximate: it counts within that statement, with each comment read as one space. " + + `Fix the syntax there: quote identifiers that contain spaces or are keywords (${quoteName("order date", dialect)}), ` + + "check the clause order, and replace any placeholder text (...)" + ) + } + // The checks below follow classifySql's conditions. + let parsed: { category?: string; statement_type?: string } | undefined + try { + parsed = getStatementTypes?.(parserSql(statement, dialect), dialect)?.statements?.[0] + } catch { + parsed = undefined + } + const reported = String(parsed?.statement_type ?? "").toUpperCase() + // An UNKNOWN type is named by its first word only when that is a known statement keyword: any other + // word is the user's text, which telemetry would record. + const first = (/^\s*([A-Za-z_]+)/.exec(maskSql(tokenizeSql(statement, dialect).tokens))?.[1] ?? "").toUpperCase() + const type = + reported && reported !== "UNKNOWN" + ? reported + : STATEMENT_KEYWORDS.has(first) + ? first + : "an unrecognized statement" + const tokens = tokenizeSql(statement, dialect).tokens + const masked = maskSql(tokens) + if (functionSafety(statement, dialect, 0).write) return writes(`${where} calls a function that can modify data or run other SQL`) + // A statement that is itself a write is named by its type, before any batch keyword inside it. + if (parsed && parsed.category !== "query") return writes(`${where} is not a read (${type})`) + if (parsed?.category === "query" && hasQueryWriteClause(statement, dialect)) { + // Quoted names keep their case; engines that store unquoted names in uppercase need it written so. + const quoted = /^(snowflake|oracle)$/i.test(dialect ?? "") + ? `${quoteName("t", dialect)}.${quoteName("UPDATE", dialect)}, keeping the qualifier as written and the column in uppercase, as this engine stores unquoted names` + : `${quoteName("t", dialect)}.${quoteName("update", dialect)}` + // Name the dotted-keyword case only when the statement has a keyword right after a dot (after a quoted + // name, or any name on ClickHouse); otherwise the hint would point away from the real write clause. + const clickhouse = dialect?.toLowerCase() === "clickhouse" + // Read on masked code (quoted names blanked, literals and comments ignored) with numbers blanked too, so + // `1. INTO` and `.5 INTO` stay a SELECT INTO: a keyword after a quoted name or a spaced dot counts; an unquoted t.update + // is a column and never reaches here. + const statementMasked = masked.replace(/(? " ".repeat(number.length)) + const dotted = ( + clickhouse ? /\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i : /(?:(?:^|[^\w$])\s*|\s)\.\s*(INTO|INSERT|UPDATE|DELETE|MERGE)\b|\.\s+(INTO|INSERT|UPDATE|DELETE|MERGE)\b/i + ).test(statementMasked) + const clause = clickhouse + ? "a write clause (SELECT ... INTO or a modifying CTE)" + : "a write clause (SELECT ... INTO, or INSERT/UPDATE/DELETE/MERGE inside a CTE)" + return writes( + !dotted + ? `${where} contains ${clause}` + : clickhouse + ? `${where} contains a write keyword that on ClickHouse counts even after a dot: quote the column, t.${quoteName("update", dialect)}` + : `${where} contains a write keyword after a quoted name or a spaced dot, such as ${quoteName("t", dialect)}.update: quote the column too, ${quoted}`, + ) + } + const keyword = batchedStatement(masked, dialect) + if (keyword) { + return writes( + `${where} holds the statement keyword ${keyword.trim().split(/\s+/)[0].toUpperCase()} outside a literal or comment; ` + + `${batchKeywordExplanation(dialect)}; quote it if it is a column name`, + ) + } + if (/^snowflake$/i.test(dialect ?? "") && masked.includes("->>")) return writes(`${where} chains statements with ->>`) + if ( + (/^(spark|databricks|hive)$/i.test(dialect ?? "") || !isModeledDialect(dialect)) && + /\bTRANSFORM\s*\(/i.test(masked) && + /\bUSING\b(?!\s*\()/i.test(masked) + ) { + return writes(`${where} runs a command through TRANSFORM ... USING`) + } + if (advancesSequence(tokens, masked, dialect)) return writes(`${where} advances a sequence`) + if (parsed?.category !== "query") return writes(`${where} is not a read (${type})`) + return writes(`${where} could not be proven read-only`) + } + return writes("the statements together could not be proven read-only") +} + // MongoDB commands are JSON, not SQL: the SQL classifier reads every one as a write, which denied // 52 of 52 Mongo reads for a read-only agent in one evaluation run. Classify them by command. const MONGO_READ_COMMANDS = new Set([ @@ -593,8 +882,13 @@ function hasLocalScratchTarget(statement: string): boolean { "i", ).exec(statement) if (!target) return false - const names = target[1].match(new RegExp(identifier, "g"))! - if (names.length > 2 || (names.length === 2 && names[0].replace(/^"|"$/g, "").toLowerCase() !== "main")) return false + const names = target[1].match(new RegExp(identifier, "g"))!.map((name) => name.replace(/^"|"$/g, "").toLowerCase()) + // The scratch database's own catalog is named scratch: scratch.t and scratch.main.t are local too. + const local = + names.length === 1 || + (names.length === 2 && (names[0] === "main" || names[0] === "scratch")) || + (names.length === 3 && names[0] === "scratch" && names[1] === "main") + if (!local) return false // A DROP statement can name more than one table, unlike the other forms. return !/^\s*DROP\b/i.test(statement) || !statement.slice(target[0].length).includes(",") } diff --git a/packages/opencode/src/altimate/tools/sql-execute.ts b/packages/opencode/src/altimate/tools/sql-execute.ts index 78a5a11d41..bcef06a84c 100644 --- a/packages/opencode/src/altimate/tools/sql-execute.ts +++ b/packages/opencode/src/altimate/tools/sql-execute.ts @@ -13,7 +13,9 @@ import { classifyAndCheck, classifyMongoCommand, computeSqlFingerprint, + explainWrite, isScratchSafeWrite, + UNAVAILABLE_NEXT_STEP, mentionsHardDenyAnywhere, } from "./sql-classify" import { statementsOf } from "./sql-tokenize" @@ -25,6 +27,8 @@ function isMongoWarehouse(name: string | undefined): boolean { return MONGO_WAREHOUSE_TYPES.has(type) } import { Telemetry } from "../telemetry" +import { PermissionV1 } from "@opencode-ai/core/v1/permission" +import { PermissionNext } from "../../permission/next" // altimate_change end // altimate_change start — progressive disclosure suggestions import { PostConnectSuggestions } from "./post-connect-suggestions" @@ -41,6 +45,8 @@ import * as Precedence from "../workspace/precedence" import { normalizeError } from "./response-normalization" // altimate_change end import { readSql } from "./sql-check" +import { NOT_OVERRIDABLE, hardBlockRefusal, writeReason } from "./read-only-sql" +import { WriteDeniedError } from "../tool-cli/permissions" import { MaterializeError, storeRows } from "./sql-materialize" import { firstTime } from "./session-hints" @@ -67,10 +73,11 @@ const STEP_REF = /\{\{([A-Za-z_]\w*)(?:\.([A-Za-z_]\w*))?\}\}/g const MAX_BOUND_ROWS = 1000 function generatedRead(sql: string, warehouse: string, stage: "source" | "result"): string { + const dialect = Registry.canonicalType(Registry.getConfig(warehouse)?.type) ?? undefined try { - return readSql(sql, Registry.canonicalType(Registry.getConfig(warehouse)?.type) ?? undefined) + return readSql(sql, dialect, { explain: false }) } catch { - throw new Error(`query_from ${stage} must be a single read-only SELECT (or WITH ... SELECT).`) + throw new Error(`query_from ${stage} must be a single read-only SELECT (or WITH ... SELECT).${writeReason(sql, dialect)}`) } } @@ -218,7 +225,8 @@ export const SqlExecuteTool = Tool.define( }) } // altimate_change start - SQL write access control - // Permission checks OUTSIDE try/catch so denial errors propagate to the framework + // Permission checks OUTSIDE the execution try/catch: a rule denial of sql_execute_write is rethrown + // with its reason below, and every other permission error propagates unchanged // MongoDB warehouses take JSON command documents; the SQL classifier would read // every one as a write. Dispatch the normalized `{command, collection}` form. const warehouse = args.warehouse || Registry.list().warehouses[0]?.name @@ -245,12 +253,19 @@ export const SqlExecuteTool = Tool.define( const blocked = classification.blocked || (jinja && mentionsHardDenyAnywhere(sql)) const query = mongo?.normalized ?? sql if (blocked) { - throw new Error( - "DROP DATABASE, DROP SCHEMA, TRUNCATE, and executable SQL comments are blocked for safety. This cannot be overridden.", - ) + const head = "DROP DATABASE, DROP SCHEMA, TRUNCATE, and executable SQL comments are blocked for safety." + // Name the matched rule, or the unreadable quote that made a word count, for the dialect that blocked it. + const blockedIn = "blockedIndex" in classification ? classification.blockedIndex : -1 + if (blockedIn >= 0) throw new Error(hardBlockRefusal(head, sql, dialects[blockedIn])) + if (jinja) + throw new Error( + `${head} ${NOT_OVERRIDABLE} dbt renders Jinja before the SQL runs, so DROP DATABASE, DROP SCHEMA or ` + + "TRUNCATE words count wherever they sit, even in a literal or comment. Remove those words, or send plain SQL without Jinja.", + ) + throw new Error(`${head} ${NOT_OVERRIDABLE}`) } if (budget && queryType !== "read") { - throw new Error("Batched queries must be read-only; run a write as its own sql_execute call.") + throw new Error("Batched queries must be read-only. To use write permission, run a write as its own sql_execute call.") } const parseError = "parseError" in classification ? classification.parseError : undefined if (!mongo && queryType === "read") { @@ -274,17 +289,60 @@ export const SqlExecuteTool = Tool.define( // the hard-deny list above still applies. if (queryType === "write" && !(isScratch(args.warehouse) && isScratchSafeWrite(sql))) { // Unprovable SQL still goes through write approval; the prompt carries the parse error. - await ctx.ask({ - permission: "sql_execute_write", - patterns: [sql.slice(0, 200)], - always: ["*"], - metadata: { - queryType, - warehouse: args.warehouse || target?.warehouse, - hardDenyChecked: true, - ...(parseError && { parseError }), - }, - }) + // A denied write says why and how to proceed, instead of a rule dump. + try { + await ctx.ask({ + permission: "sql_execute_write", + patterns: [sql.slice(0, 200)], + always: ["*"], + metadata: { + queryType, + warehouse: args.warehouse || target?.warehouse, + hardDenyChecked: true, + ...(parseError && { parseError }), + }, + }) + } catch (error) { + let permitted: string[] = [] + const explain = (readOnly: boolean, cli = false) => + deniedWriteMessage({ + sql, + dialects, + jinja, + mongo: mongo !== null, + scratch: isScratch(args.warehouse), + warehouseGiven: !!args.warehouse, + readOnly, + cli, + dbt: target?.dbt === true, + permitted, + }) + // The MCP server and `altimate tool` refuse writes unless --allow-write was given. + if (error instanceof WriteDeniedError) throw new Error(`${explain(true, true)} ${error.message}`) + if (!(error instanceof PermissionV1.DeniedError || error instanceof PermissionNext.DeniedError)) throw error + const rules: Array<{ permission?: string; pattern?: string; action?: string }> = Array.isArray(error.ruleset) + ? error.ruleset + : [] + // Rules apply last-match-wins: the agent is read-only when the last catch-all rule denies and + // nothing after it allows or asks (an agent's own deny can override a user's earlier "ask"). + let lastCatchAllDeny = -1 + rules.forEach((rule, index) => { + if (rule.pattern === "*" && rule.action === "deny") lastCatchAllDeny = index + }) + // Name only patterns still in effect (after that deny), from this permission's own rules (wildcard- + // permission rules such as the builder's "*": "allow" are about every tool), and never a catch-all, + // which would read as "everything is allowed". Allow before ask. + const own = rules + .slice(lastCatchAllDeny + 1) + .filter((rule) => rule.permission === "sql_execute_write" && rule.pattern && rule.pattern !== "*") + permitted = [...own.filter((rule) => rule.action === "allow"), ...own.filter((rule) => rule.action === "ask")].map( + (rule) => rule.pattern!, + ) + // With no catch-all deny, writes the rules do not name fall to the default ("ask"). + throw new Error( + explain(lastCatchAllDeny >= 0 && !rules.slice(lastCatchAllDeny + 1).some((rule) => rule.action !== "deny")), + ) + } } // altimate_change end @@ -717,10 +775,87 @@ function classifyEvery(sql: string, dialects: (string | undefined)[]) { return { queryType: results.some((result) => result.queryType === "write") ? ("write" as const) : ("read" as const), blocked: results.some((result) => result.blocked), + blockedIndex: results.findIndex((result) => result.blocked), ...(parseError && { parseError }), } } +// altimate_change start — a denied write says why and how to proceed +/** The error a read-only agent gets when its query counts as a write: the reason, then what to do next, + * so the agent fixes the query instead of resending it. */ +export function deniedWriteMessage(input: { + sql: string + dialects: (string | undefined)[] + jinja: boolean + mongo: boolean + scratch: boolean + warehouseGiven: boolean + readOnly?: boolean + /** Refused because this MCP server or tool CLI run was started without --allow-write. */ + cli?: boolean + /** The default route is dbt: passing a warehouse would also move the query off dbt, so no hint names it. */ + dbt?: boolean + /** Configured sql_execute_write patterns that allow or ask, named so the agent can comply. Single-quoted, so + * telemetry's literal masking keeps config text out of recorded errors. */ + permitted?: string[] +}): string { + const readOnly = input.readOnly !== false + const head = input.cli + ? "sql_execute did not run this query. Write permission is disabled for this run, and the query counts as a write because" + : readOnly + ? "sql_execute did not run this query. This agent may only read (write permission is denied), and the query counts as a write because" + : "sql_execute did not run this query. A sql_execute_write permission rule denies it, and the query counts as a write because" + if (input.jinja) { + return `${head} it contains Jinja ({{ }}, {% %} or {# #}), which dbt renders and runs before the SQL. Send plain SQL without Jinja.` + } + if (input.mongo) { + return `${head} it is a MongoDB write (a write command, or an aggregate with a $out or $merge stage). Use a read command (find, aggregate, countDocuments, distinct) instead.` + } + // Classify once per dialect. Prefer a dialect that reads the text and names a concrete write over one that + // cannot parse it. + const results = input.dialects.map((d) => ({ dialect: d, ...classifyAndCheck(input.sql, d) })) + let chosen: ReturnType | undefined + for (const result of results) { + if (result.queryType !== "write") continue + const explanation = explainWrite(input.sql, result.dialect) + if (!explanation.unreadable) { + chosen = explanation + break + } + chosen ??= explanation + } + const { reason, unreadable, unavailable, residue } = chosen ?? explainWrite(input.sql, undefined) + // Without a warehouse (and off the dbt route, where a warehouse also moves the query off dbt), a query the + // reachable dialects disagree on, or cannot read, may be fine in the real warehouse's dialect. + const disagree = results.some((result) => result.queryType === "read" && !result.blocked) + // Shell syntax is not SQL in any dialect, so checking another dialect cannot help. + const dialectHint = + residue || input.warehouseGiven || input.dbt || input.dialects.length < 2 + ? "" + : disagree + ? " No warehouse was given and the reachable dialects disagree on whether this is a write; pass warehouse to check it in that warehouse's dialect only." + : unreadable + ? " No warehouse was given, so the query was checked in every dialect it could reach; pass warehouse to check it in that warehouse's dialect only." + : "" + const next = unavailable + ? UNAVAILABLE_NEXT_STEP + : unreadable + ? "Fix the query and call sql_execute again; the same text will be refused again." + + (readOnly ? "" : " The configured sql_execute_write rules may still deny it once it parses.") + + dialectHint + : input.cli + ? "If a write is intended, see the --allow-write note at the end; otherwise rewrite it as a single read (SELECT, or WITH ... SELECT)." + : !readOnly + ? "Change it to a statement the configured sql_execute_write rules allow" + + (input.permitted?.length ? ` (they allow or ask for: ${input.permitted.slice(0, 10).map((p) => `'${p.replaceAll("\\", "\\\\").replaceAll("'", "''")}'`).join(", ")})` : "") + + ", or ask the user to change the rules." + : input.scratch + ? "On scratch, only CREATE/DROP/ALTER of local tables and views and INSERT/UPDATE/DELETE on them run without write permission, each call without reads; other statements (ATTACH, COPY, INSTALL, SET, ...) need write permission." + : "Rewrite it as a single read (SELECT, or WITH ... SELECT). To keep an intermediate result, store it in scratch with sql_materialize if that tool is available." + return `${head} ${reason}. ${next}${unreadable ? "" : dialectHint}` +} +// altimate_change end + /** Dialects whose string literals treat a backslash as an escape character. */ const BACKSLASH_ESCAPE_TYPES = new Set(["mysql", "bigquery", "snowflake", "databricks", "clickhouse", "redshift"]) /** Dialects with no `''` escape inside a string literal; a quote is escaped with a backslash. */ diff --git a/packages/opencode/src/altimate/tools/sql-explain.ts b/packages/opencode/src/altimate/tools/sql-explain.ts index 699e884fa7..d9b5635262 100644 --- a/packages/opencode/src/altimate/tools/sql-explain.ts +++ b/packages/opencode/src/altimate/tools/sql-explain.ts @@ -8,6 +8,7 @@ import * as Precedence from "../workspace/precedence" import { validateWarehouseName } from "./input-validation" import * as Registry from "../native/connections/registry" import { classifyAndCheck, isSingleQuery } from "./sql-classify" +import { hardBlockRefusal } from "./read-only-sql" import { maskSql, statementsOf, tokenizeSql } from "./sql-tokenize" /** @@ -108,7 +109,7 @@ export const SqlExplainTool = Tool.define("sql_explain", { /^(EXPLAIN|ANALY[SZ]E|VERBOSE)\b|^\((?![(\s]*(SELECT|WITH|VALUES|TABLE|FROM)\b)/i.test(statements[0] ?? "") || (lexical.complete && /^\s*;/.test(maskSql(lexical.tokens))) let error: string | undefined - if (blocked) error = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + if (blocked) error = hardBlockRefusal("DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety.", args.sql, dialect) else if (!lexical.complete) error = lexical.backslash ? "The SQL has a backslash in a quoted string, which this dialect can read as an escape, so it is not explained. Build that character with the dialect's character function instead (CHR(92) or CHAR(92), depending on the dialect) to get a plan." diff --git a/packages/opencode/src/altimate/tools/sql-materialize.ts b/packages/opencode/src/altimate/tools/sql-materialize.ts index 9a5c79b01a..d405e11abb 100644 --- a/packages/opencode/src/altimate/tools/sql-materialize.ts +++ b/packages/opencode/src/altimate/tools/sql-materialize.ts @@ -8,6 +8,7 @@ import * as Registry from "../native/connections/registry" import { SCRATCH_NAME, withScratchConnection, isScratch } from "../native/connections/scratch" import { classifyAndCheck, classifyMongoCommand } from "./sql-classify" import { readSql } from "./sql-check" +import { writeReason } from "./read-only-sql" import { lintSqlResult } from "./sql-result-lint" import * as Precedence from "../workspace/precedence" import { executeQuery, type QueryContext } from "../native/query-execution" @@ -214,11 +215,12 @@ function assertReadOnlySource(warehouse: string, sql: string): { mongo: boolean; const { queryType, blocked } = classifyAndCheck(sql, Registry.canonicalType(type) ?? undefined) try { if (blocked || queryType !== "read") throw new Error("Not a read") - return { mongo: false, sql: readSql(sql, Registry.canonicalType(type) ?? undefined) } + return { mongo: false, sql: readSql(sql, Registry.canonicalType(type) ?? undefined, { explain: false }) } } catch { throw new MaterializeError( "sql_materialize only reads from the source warehouse: use a single read-only SELECT (or WITH ... SELECT), " + - "without modifying CTEs, SELECT INTO or side-effect functions. Its only write target is the scratch database.", + "without modifying CTEs, SELECT INTO or side-effect functions. Its only write target is the scratch database." + + writeReason(sql, Registry.canonicalType(type) ?? undefined), ) } } diff --git a/packages/opencode/src/altimate/tools/sql-result-lint.ts b/packages/opencode/src/altimate/tools/sql-result-lint.ts index 82aa47caf5..5716d395ff 100644 --- a/packages/opencode/src/altimate/tools/sql-result-lint.ts +++ b/packages/opencode/src/altimate/tools/sql-result-lint.ts @@ -56,7 +56,8 @@ export async function lintSqlResult(sql: string, warehouse: string | undefined, const name = warehouse ?? Registry.list().warehouses[0]?.name const type = Registry.canonicalType(name ? Registry.getConfig(name)?.type : undefined) // The general classifier also labels modifying CTEs and SELECT INTO as queries. - readSql(sql, type ?? undefined) + // Only the yes/no matters here: skip the refusal's explanation on this per-result path. + readSql(sql, type ?? undefined, { explain: false }) const timeout = new Promise((resolve) => { timer = setTimeout(() => { slowSessions.add(sessionID) diff --git a/packages/opencode/test/altimate/mcp-server/workspace.test.ts b/packages/opencode/test/altimate/mcp-server/workspace.test.ts index 2162004abc..623d645969 100644 --- a/packages/opencode/test/altimate/mcp-server/workspace.test.ts +++ b/packages/opencode/test/altimate/mcp-server/workspace.test.ts @@ -33,6 +33,9 @@ test("only the supported workspace read capabilities cross the facade", () => { test("workspace SQL reuses the native classifier and refuses mutation, hidden side effects and absent SQL", () => { expect(() => checkEngineRead("snowflake_execute_database_query", { query: "SELECT 1" })).not.toThrow() + expect(() => checkEngineRead("postgresql_execute_database_query", { query: "SELECT 1; DELETE FROM t" })).toThrow( + "statement 2 of 2 is not a read (DELETE)", + ) expect(() => checkEngineRead("postgresql_execute_database_query", { sql: "SELECT count(*) FROM orders" }), ).not.toThrow() diff --git a/packages/opencode/test/altimate/sql-materialize.test.ts b/packages/opencode/test/altimate/sql-materialize.test.ts index 05b9e0a5eb..6de6c541ba 100644 --- a/packages/opencode/test/altimate/sql-materialize.test.ts +++ b/packages/opencode/test/altimate/sql-materialize.test.ts @@ -347,6 +347,10 @@ describe("sql_materialize", () => { /only reads/, ) } + // The refusal names the statement that writes. + await expect( + materialize({ source_warehouse: "ordersdb", sql: "SELECT 1; DELETE FROM orders", target_table: "nope" }), + ).rejects.toThrow("statement 2 of 2 is not a read (DELETE)") const db = new Database(ordersDb, { readonly: true }) expect((db.query("SELECT count(*) AS n FROM orders").get() as any).n).toBe(4) db.close() diff --git a/packages/opencode/test/altimate/sql-read-syntax.test.ts b/packages/opencode/test/altimate/sql-read-syntax.test.ts index c8b2a149c5..7500a77692 100644 --- a/packages/opencode/test/altimate/sql-read-syntax.test.ts +++ b/packages/opencode/test/altimate/sql-read-syntax.test.ts @@ -60,7 +60,7 @@ describe("read-only dialect syntax", () => { ]) { expect(classifyAndCheck(sql, "duckdb").queryType).toBe("write") } - expect(classifyAndCheck("SELECT 10//3; TRUNCATE users", "duckdb")).toEqual({ queryType: "write", blocked: true }) + expect(classifyAndCheck("SELECT 10//3; TRUNCATE users", "duckdb")).toEqual({ queryType: "write", blocked: true, cause: "TRUNCATE" }) }) test("unsupported dialects do not inherit DuckDB-only syntax", () => { diff --git a/packages/opencode/test/altimate/tool-cli/runner.test.ts b/packages/opencode/test/altimate/tool-cli/runner.test.ts index 67cbae0f0e..5fd13bcd34 100644 --- a/packages/opencode/test/altimate/tool-cli/runner.test.ts +++ b/packages/opencode/test/altimate/tool-cli/runner.test.ts @@ -136,7 +136,9 @@ describe("tool run", () => { test("a write is denied without --allow-write", async () => { const result = await runner.run("sql_execute", { query: "CREATE TABLE t (a int)" }) expect(result.status).toBe("error") - expect(result.output).toBe("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.") + // The refusal says why the query counts as a write, then how to enable writes. + expect(result.output).toContain("Write permission is disabled for this run, and the query counts as a write because it is not a read (CREATE TABLE)") + expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) test("config-changing tools need --allow-write", async () => { diff --git a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts index 96eca55685..c3752dd339 100644 --- a/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts +++ b/packages/opencode/test/altimate/tools/sql-comment-safety.test.ts @@ -265,6 +265,8 @@ test("on the dbt route, Jinja in a comment or literal is a write, and a hard-den expect(write.asked).toEqual(["sql_execute_write"]) const drop = await run("SELECT 1 AS x -- {% do run_query('DROP SCHEMA prod CASCADE') %}") await expect(drop.result).rejects.toThrow("blocked for safety") + // Blocked by the Jinja word scan alone (the SQL reads the words as a comment): the error says why. + await expect(drop.result).rejects.toThrow("dbt renders") // A Jinja comment removes text, which can expose a statement the SQL lexing reads as a literal. const hidden = await run("SELECT 'x' /* {# */ || ' #} */) AS q ; DROP SCHEMA s CASCADE ; SELECT 1 -- '") await expect(hidden.result).rejects.toThrow("blocked for safety") diff --git a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts index 3adc47d5c8..d1aa221be7 100644 --- a/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts +++ b/packages/opencode/test/altimate/tools/sql-execute-query-from.test.ts @@ -205,6 +205,24 @@ describe("sql_execute generated reads", () => { }) } + test("a refused source says once which statement writes", async () => { + const tool = await initTool(SqlExecuteTool) + const error = await tool + .execute({ query_from: { ...source, sql: "SELECT 1; DELETE FROM orders" }, warehouse: "analytics" }, ctx) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("query_from source must be a single read-only SELECT") + expect(error.split("statement 2 of 2 is not a read (DELETE)").length).toBe(2) + expect(dispatch).not.toHaveBeenCalled() + }) + + test.each(["SELECT 1; SELECT 2", "SHOW TABLES"])("explains the refused source shape %s", async (sql) => { + const tool = await initTool(SqlExecuteTool) + await expect(tool.execute({ query_from: { ...source, sql }, warehouse: "analytics" }, ctx)).rejects.toThrow( + "send a single SELECT or WITH query", + ) + expect(dispatch).not.toHaveBeenCalled() + }) + for (const sql of [ "DELETE FROM orders", "CREATE TEMP TABLE generated AS SELECT 1", diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts new file mode 100644 index 0000000000..18c476fd57 --- /dev/null +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard-explain.test.ts @@ -0,0 +1,430 @@ +import { describe, expect, test } from "bun:test" +import { mkdtempSync, rmSync, writeFileSync } from "node:fs" +import { tmpdir } from "node:os" +import { join } from "node:path" +import { classifyAndCheck, explainWrite, shellResidue } from "../../../src/altimate/tools/sql-classify" +import { hardBlockRefusal, readSql, requireReadOnlyQuery, writeReason } from "../../../src/altimate/tools/read-only-sql" + +describe("shellResidue", () => { + const cases: Record = { + "SELECT 1 2>/dev/null": "2>/dev/null", + "SELECT * FROM t LIMIT 5 2>&1": "2>&1", + "SELECT * FROM t >/dev/null": ">/dev/null", + "SELECT * FROM t > /home/someone/private/out.csv": "> ", + "SELECT * FROM t | grep private-name": "| grep ...", + "SELECT * FROM t > out.csv": "> ", + "SELECT * FROM t | head -20": "| head ...", + "SELECT * FROM t LIMIT 5 2>&1 | head -n 20": "2>&1`, `| head ...", + "SELECT * FROM t; 2>/dev/null": "2>/dev/null", + "SELECT a FROM t ORDER BY a 2>/dev/null LIMIT 5": "2>/dev/null", + "SELECT a FROM t 2>/dev/null | head -5": "2>/dev/null`, `| head ...", + } + for (const [sql, residue] of Object.entries(cases)) { + test(`finds ${residue}`, () => { + expect(shellResidue(sql, "postgres")).toBe(residue) + // The residue makes the text unreadable, so it is never classified as a read. + expect(classifyAndCheck(sql, "postgres").queryType).toBe("write") + }) + } + + test("on ClickHouse, whose parser accepts trailing text, a redirect is still named and not run", () => { + for (const [sql, residue] of [ + ["SELECT 1 2>/dev/null", "2>/dev/null"], + ["SELECT * FROM t LIMIT 5 2>&1", "2>&1"], + ["SHOW TABLES 2>/dev/null", "2>/dev/null"], + ["DESCRIBE TABLE t 2>&1", "2>&1"], + ]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("write") + expect(shellResidue(sql, "clickhouse")).toBe(residue) + } + for (const sql of ["SELECT a > 2 FROM t", "SELECT '2>/dev/null'", "SELECT 1 -- 2>/dev/null", "SELECT a || tail FROM t"]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") + } + expect(classifyAndCheck("SELECT * FROM t | head -5", "clickhouse").queryType).toBe("write") + expect(shellResidue("SELECT * FROM t | head -5", "clickhouse")).toBe("| head ...") + for (const sql of ["SELECT a || tail FROM t", "SELECT * FROM t WHERE a > b.csv", "SELECT x FROM t WHERE a = b | head"]) { + expect(classifyAndCheck(sql, "clickhouse").queryType).toBe("read") + } + // A write keeps its own reason rather than a parser failure. + expect(explainWrite("DELETE FROM t 2>/dev/null", "clickhouse").reason).toBe("it is not a read (DELETE)") + }) + + test("a comparison is not a redirect", () => { + expect(shellResidue("SELECT a FROM t WHERE x > 2", "postgres")).toBeUndefined() + expect(shellResidue("SELECT a FROM t WHERE x >= 2.5", "postgres")).toBeUndefined() + }) + + test("an appended redirect is named as written, and several pipes by their last command", () => { + expect(shellResidue("SELECT * FROM t 2>> /dev/null", "postgres")).toBe("2>>/dev/null") + expect(shellResidue("SELECT * FROM t | grep -i private | head", "postgres")).toBeUndefined() + }) + + // Timing compares two sizes on the same host instead of a wall-clock bound: linear work grows about 8x + // from 1x to 8x input, quadratic about 64x. Each size takes its fastest of three runs, so one scheduler + // stall on a loaded host does not read as growth. + const growth = (build: (n: number) => string, n: number) => { + const time = (sql: string) => { + let best = Infinity + for (let run = 0; run < 3; run++) { + const start = performance.now() + explainWrite(sql, "postgres") + shellResidue(sql, "postgres") + best = Math.min(best, performance.now() - start) + } + return best + } + time(build(n)) // warm up + return time(build(n * 8)) / Math.max(time(build(n)), 1) + } + + test("a long literal before a syntax error is explained in linear time", () => { + expect(growth((n) => `SELECT '${"x".repeat(n)}' FROM WHERE`, 25_000)).toBeLessThan(30) + }) + + test("a crafted tail is scanned in linear time", () => { + // The tail patterns see at most 400 characters, so a longer crafted tail costs no more. + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)}x;y`, 2_000)).toBeLessThan(30) + expect(growth((n) => `SELECT * FROM t ${"| head ".repeat(n)};y`, 1_500)).toBeLessThan(30) + }) + + test("a comparison before the residue is kept", () => { + expect(shellResidue("SELECT a FROM t WHERE flag OR x > 1.5 2>/dev/null", "postgres")).toBe("2>/dev/null") + expect(shellResidue("SELECT a FROM t WHERE x > t.total 2>/dev/null", "postgres")).toBe("2>/dev/null") + }) + + test("SQL that parses is never offered for removal", () => { + expect(shellResidue("SELECT a FROM t WHERE a > out.csv", "postgres")).toBeUndefined() + expect(shellResidue("SELECT a FROM t WHERE a > b / 2", "postgres")).toBeUndefined() + }) + + test("text inside a comment or literal is not residue", () => { + expect(shellResidue("SELECT 1 -- 2>/dev/null", "postgres")).toBeUndefined() + expect(shellResidue("SELECT '2>/dev/null'", "postgres")).toBeUndefined() + }) + + test("a write after residue is named, not hidden in the residue", () => { + const sql = "SELECT 1 FROM t | head -5; DROP TABLE t" + expect(shellResidue(sql, "postgres")).toBeUndefined() + expect(explainWrite(sql, "postgres").reason).not.toContain("shell syntax") + }) + + test("a write followed by residue is not offered as a read", () => { + expect(shellResidue("DELETE FROM t 2>/dev/null", "postgres")).toBeUndefined() + expect(explainWrite("DELETE FROM t 2>/dev/null", "postgres").reason).not.toContain("shell syntax") + }) +}) + +describe("other read-only refusals carry the reason", () => { + test("sql_check (readSql)", () => { + expect(() => readSql("SELECT 1 2>/dev/null", "postgres")).toThrow("`2>/dev/null`") + expect(() => readSql("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2") + }) + + test("qualified columns named like keywords are reads here too", () => { + expect(readSql("SELECT o.update, o.delete FROM orders o", "postgres")).toBe("SELECT o.update, o.delete FROM orders o") + expect(readSql("SELECT o.replace FROM orders o", "postgres")).toBe("SELECT o.replace FROM orders o") + expect(() => readSql("REPLACE INTO orders VALUES (1)", "mysql")).toThrow() + expect(() => readSql("SELECT 1. INTO c FROM orders", "postgres")).toThrow() + }) + + test("a word only the stricter sql_check list refuses is named", () => { + expect(() => readSql("SELECT x AS load FROM t", "postgres")).toThrow("statement word LOAD") + // Not named when something else also refuses it (the leading parenthesis). + expect(() => readSql("(SELECT x AS load FROM t)", "postgres")).not.toThrow("statement word") + expect(writeReason("SELECT x AS load FROM t", "postgres")).toContain("statement word LOAD") + }) + + test("parser details end without stray punctuation", () => { + expect(explainWrite("SELECT a FROM WHERE (((", "postgres").reason).not.toMatch(/,\)/) + }) + + test("the result lint path can skip the explanation", () => { + expect(() => readSql("SELECT 1; DELETE FROM t", "postgres", { explain: false })).toThrow( + /^This operation only accepts a single read-only SELECT \(or WITH \.\.\. SELECT\); it never writes or fixes data\.$/, + ) + }) + + test("a closed executable comment is named, not treated as an open quote", () => { + const reason = explainWrite("SELECT 1 /*! + 1 */", "mysql").reason + expect(reason).toContain("executable comment") + expect(reason).not.toContain("unterminated") + const refusal = writeReason("SELECT 1 /*! + 1 */", "mysql") + expect(refusal).toContain("hard-blocked statement") + expect(refusal).toContain("executable comment") + expect(refusal).not.toContain("Until it can be read") + // The marker inside a literal is not a comment. + expect(explainWrite("SELECT '/*! x' AS a, 'unclosed", "mysql").reason).not.toContain("executable comment") + }) + + test("a hard-blocked statement is named as such", () => { + expect(writeReason("SELECT 1; DROP DATABASE prod", "postgres")).toContain( + "statement 2 of 2 is a hard-blocked statement (DROP DATABASE)", + ) + // The matched rule is named by a fixed label, never with SQL text. + expect(writeReason("SELECT 1; TRUNCATE TABLE secret_t", "postgres")).toContain("(TRUNCATE)") + expect(writeReason("DROP SCHEMA s", "postgres")).toContain("it holds a hard-blocked statement (DROP SCHEMA)") + expect(writeReason("SELECT 1 /*! + 1 */", "mysql")).toContain("(an executable comment)") + const nested = writeReason("SELECT * FROM query('DROP SCHEMA secret_s')", "duckdb") + expect(nested).toContain("(SQL run from a string literal)") + expect(nested).not.toContain("secret_s") + // The label is the rule the classifier blocked on: a qualified column named truncate is not TRUNCATE, + // a Unicode-escaped literal holds no hard-deny word, and dynamic SQL is named as such. + expect(writeReason("SELECT q.truncate FROM query('DROP SCHEMA s') q", "duckdb")).toContain("(SQL run from a string literal)") + expect(writeReason("INSERT INTO t VALUES (U&'d!0061t' UESCAPE '!')", "postgres")).toContain("Unicode escape") + expect(writeReason("EXEC sp_x /* drop schema s */", "sqlserver")).toContain("(dynamic SQL") + // Only fixed words reach the label: a name after DROP inside a TRUNCATE target is not echoed. + const target = writeReason("SELECT 1 THEN TRUNCATE IDENTIFIER(drop secret_tbl);", "postgres") + expect(target).toContain("(TRUNCATE)") + expect(target).not.toMatch(/secret_tbl/i) + // SQL Server's query() is XQuery, so a qualified column named truncate beside it is a read. + expect(classifyAndCheck("SELECT q.truncate FROM query('DROP SCHEMA s') q", "sqlserver")).toMatchObject({ queryType: "read", blocked: false }) + // An unclosed quote holding a blocked word names the quote first. + const reason = writeReason("SELECT a FROM t WHERE n = 'do not truncate", "postgres") + expect(reason.indexOf("unterminated")).toBeGreaterThan(-1) + expect(reason.indexOf("unterminated")).toBeLessThan(reason.indexOf("Until it can be read")) + expect(reason).not.toContain("cannot be allowed") + // A real hard block outside the open quote is not described as sitting inside it. + expect(writeReason("DROP DATABASE x; SELECT 'abc", "postgres")).toContain("inside that quoted text or outside it") + }) + + test("a SELECT ... INTO the parser cannot read is a write, not a syntax error", () => { + for (const sql of ["SELECT a FROM t INTO OUTFILE '/tmp/x'", "SELECT a FROM t LIMIT 1 INTO @v", "SELECT 0x1.INTO t FROM"]) { + const reason = explainWrite(sql, "mysql").reason + expect(reason).toContain("write clause") + expect(reason).not.toContain("could not read") + } + // INTO inside a literal or after a dot is not an INTO clause. + expect(explainWrite("SELECT 'into' FROM WHERE", "postgres").reason).toContain("could not read") + expect(explainWrite("SELECT t.into FROM WHERE", "postgres").reason).toContain("could not read") + }) + + test("a hard-block refusal claims it cannot be overridden only for a real hard block", () => { + const head = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + expect(hardBlockRefusal(head, "SELECT 1; DROP DATABASE p", "postgres")).toContain("cannot be overridden") + const open = hardBlockRefusal(head, "SELECT * FROM t WHERE note = 'don't truncate'", "postgres") + expect(open).not.toContain("cannot be overridden") + expect(open).toContain("write a single quote as ''") + }) + + test("a missing parser is reported as unavailable, not as a syntax error", async () => { + // The parser binding is read once at import, so stub it in a fresh process run outside the package + // (its test preload loads the classifier first; mock.module also leaks across files in one process). + const dir = mkdtempSync(join(tmpdir(), "guard-unavailable-")) + const src = join(import.meta.dir, "../../../src/altimate/tools") + writeFileSync( + join(dir, "unavailable.test.ts"), + `import { expect, mock, test } from "bun:test" +mock.module("@altimateai/altimate-core", () => ({})) +test("unavailable", async () => { + const { explainWrite, UNAVAILABLE_NEXT_STEP } = await import(${JSON.stringify(join(src, "sql-classify"))}) + const { writeReason } = await import(${JSON.stringify(join(src, "read-only-sql"))}) + const explained = explainWrite("SELECT 1", "postgres") + expect(explained.unavailable).toBe(true) + expect(explained.reason).not.toContain("could not read") + expect(writeReason("SELECT 1", "postgres")).toContain(UNAVAILABLE_NEXT_STEP) + // An installation failure is not a permission decision, in words or in its telemetry class. + expect(writeReason("SELECT 1", "postgres")).not.toContain("permission") +}) +`, + ) + try { + const run = Bun.spawnSync([process.execPath, "test", "./unavailable.test.ts"], { + cwd: dir, + stdout: "pipe", + stderr: "pipe", + }) + const output = run.stdout.toString() + run.stderr.toString() + // Bun can crash during cleanup after printing a complete test summary. + expect(output).toMatch(/^\s*[1-9]\d* pass\s*$/m) + expect(output).toMatch(/^\s*0 fail\s*$/m) + } finally { + rmSync(dir, { recursive: true, force: true }) + } + }, 60_000) + + test.each([ + ["SELECT 1; SELECT 2", "more than one statement"], + ["SHOW TABLES", "not a SELECT or WITH query"], + ["SELECT pg_sleep(1)", "not known to be read-only"], + ])("explains the unsupported read shape %s", (sql, cause) => { + const reason = writeReason(sql, "postgres") + expect(reason).toContain(cause) + expect(reason).toContain("send a single SELECT or WITH query") + }) + + test("a read starting with a parenthesis is told to start with SELECT or WITH", () => { + for (const sql of ["(SELECT 1)", "(SELECT 1) UNION ALL (SELECT 2)"]) { + expect(() => readSql(sql, "postgres")).toThrow("it starts with a parenthesis") + } + }) + + test("a check on SQL built around user input names the input, not positions in the built text", () => { + let message = "" + try { + requireReadOnlyQuery("SELECT 1 WHERE (a = 1; DELETE FROM t)", "postgres", "where_clause") + } catch (error) { + message = (error as Error).message + } + expect(message).toContain("The where_clause must be part of a single read-only query") + expect(message).not.toContain("column") + }) + + test("data_diff's embedded-query check names its reason too", () => { + expect(() => requireReadOnlyQuery("SELECT 1; DELETE FROM t", "postgres")).toThrow("statement 2 of 2 is not a read (DELETE)") + expect(() => requireReadOnlyQuery("SELECT 1; SELECT 2", "postgres")).toThrow("more than one statement") + }) + + test("SQL Server's XML .query() takes XQuery, so the read is accepted, as in the classifier", () => { + const sql = "SELECT x.query('/a/b') AS v FROM t" + expect(readSql(sql, "sqlserver")).toBe(sql) + expect(writeReason(sql, "sqlserver")).toBe("") + }) + + test("a single read calling query() is refused for the function", () => { + const sql = "SELECT * FROM query('SELECT 1 AS private_alias')" + const reason = writeReason(sql, "duckdb") + expect(reason).toContain("calls query()") + expect(reason).not.toContain("Invalid query shape") + expect(reason).not.toContain("private_alias") + expect(() => readSql(sql, "duckdb")).toThrow("calls query()") + }) + + test("a refusal that is not about writing stays as it was", () => { + expect(writeReason("SELECT 1", "postgres")).toBe("") + }) +}) + +describe("explainWrite", () => { + test("names shell residue", () => { + const result = explainWrite("SELECT 1 2>/dev/null", "postgres") + expect(result).toEqual({ unreadable: true, residue: true, reason: expect.stringContaining("`2>/dev/null`") }) + }) + + test("carries the parser's position", () => { + const result = explainWrite("SELECT Order Date FROM orders", "postgres") + expect(result.unreadable).toBe(true) + expect(result.reason).toMatch(/line 1, column \d+/) + }) + + test("explains an unterminated quote", () => { + const result = explainWrite("SELECT 'it\\'s' FROM t", "postgres") + expect(result.unreadable).toBe(true) + expect(result.reason).toContain("unterminated") + }) + + test("names the first write statement", () => { + expect(explainWrite("SELECT 1; SELECT 2; DROP TABLE t", "postgres")).toEqual({ + unreadable: false, + reason: "statement 3 of 3 is not a read (DROP TABLE)", + }) + expect(explainWrite("COPY INTO orders FROM @stage", "snowflake").reason).toBe("it is not a read (COPY)") + }) + + test("a TRANSFORM call outside Spark and Hive does not hide the statement type", () => { + expect(explainWrite("DELETE FROM t USING u WHERE transform(t.x) = 1", "postgres").reason).toBe("it is not a read (DELETE)") + }) + + test("a plain write on SQL Server or an unmodeled dialect is named by its type", () => { + for (const dialect of ["sqlserver", undefined]) { + expect(explainWrite("DELETE FROM orders", dialect).reason).toBe("it is not a read (DELETE)") + expect(explainWrite("INSERT INTO t VALUES (1)", dialect).reason).toBe("it is not a read (INSERT)") + } + }) + + test("parser messages keep no token text", () => { + const reason = explainWrite("SELECT set FROM t", "postgres").reason + expect(reason).toContain("line 1, column") + expect(reason).not.toContain("Set") + expect(reason).not.toContain("a token") + for (const sql of [ + "SELECT customer_secret_name(a FROM t", + "SELECT customer_secret_name customer_x customer_y FROM t", + "SELECT a FROM customer_secret_table WHERE (((", + "SELECT CAST(a AS int 'customer_it''s secret') FROM t", + ]) { + const message = explainWrite(sql, "sqlite").reason + expect(message).toContain("could not read") + expect(message).not.toMatch(/customer_/) + } + }) + + test("a SELECT INTO on SQL Server is named as a write clause, not a keyword to quote", () => { + for (const dialect of ["sqlserver", undefined]) { + expect(explainWrite("SELECT * INTO c FROM t", dialect).reason).toContain("write clause") + } + }) + + test("a plain SELECT INTO is named as a write clause without the quoted-name hint", () => { + const reason = explainWrite("SELECT a INTO newt FROM t", "postgres").reason + expect(reason).toContain("write clause") + expect(reason).not.toContain("quoted name") + }) + + test("a spaced dot gets the quoting hint; a quoted name inside a comment does not", () => { + expect(explainWrite("SELECT t . update FROM t", "sqlserver").reason).toContain("spaced dot") + expect(explainWrite('SELECT a INTO newt FROM t -- "t".update', "postgres").reason).not.toContain("spaced dot") + expect(explainWrite(`SELECT '"t".update' INTO c FROM t`, "postgres").reason).not.toContain("spaced dot") + for (const sql of ["SELECT 1. INTO c FROM t", "SELECT 1 . INTO c FROM t", "SELECT .5 INTO c FROM t", "SELECT -.5 INTO c FROM t"]) { + expect(explainWrite(sql, "postgres").reason).not.toContain("spaced dot") + } + }) + + test("a quoted qualifier gets a specific hint", () => { + expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).toContain('"t"."update"') + expect(explainWrite('SELECT "t".update FROM t', "postgres").reason).not.toContain("uppercase") + const upper = explainWrite('SELECT "T".update FROM t', "snowflake").reason + expect(upper).toContain('"t"."UPDATE", keeping the qualifier as written') + expect(upper).not.toContain('"t"."update"') + expect(writeReason("SELECT x AS load FROM t", "snowflake")).toContain("in uppercase") + expect(writeReason("SELECT x AS load FROM t", "postgres")).not.toContain("uppercase") + // Where double quotes make a string, the hints use backticks. + expect(explainWrite("SELECT `t`.update FROM t", "mysql").reason).toContain("`t`.`update`") + expect(explainWrite("SELECT Order Date FROM orders", "mysql").reason).toContain("(`order date`)") + expect(explainWrite("SELECT Order Date FROM orders", "postgres").reason).toContain('("order date")') + expect(explainWrite("SELECT Order Date FROM orders", "sqlserver").reason).toContain("([order date])") + expect(explainWrite("SELECT t.update FROM t", "clickhouse").reason).toContain("t.`update`") + }) + + test("every write in the guard corpus is a write with a specific reason", () => { + const everywhere = [ + "INSERT INTO t VALUES (1)", "UPDATE t SET a = 1", "DELETE FROM t", "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN DELETE", + "CREATE TABLE t (a INT)", "DROP TABLE t", "ALTER TABLE t ADD COLUMN c INT", "COPY INTO t FROM @s", "SELECT 1; DELETE FROM t", + "WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t", "SELECT 1. INTO c FROM t", + ] + const cases: Array<[string, string | undefined]> = [ + ...["postgres", "snowflake", "duckdb", "sqlserver", "bigquery", undefined].flatMap((d) => everywhere.map((sql) => [sql, d] as [string, string | undefined])), + ["SELECT exec FROM t", "sqlserver"], + ["SELECT nextval('s')", "postgres"], + ["SELECT NEXT VALUE FOR s", "sqlserver"], + ] + for (const [sql, dialect] of cases) { + expect({ dialect, sql, type: classifyAndCheck(sql, dialect).queryType }).toEqual({ dialect, sql, type: "write" }) + const reason = explainWrite(sql, dialect).reason + // Every corpus write parses, so a parser-failure reason would be generic too. + const specific = reason.length > 10 && !reason.includes("could not be proven") && !reason.includes("could not read") + expect({ dialect, sql, specific }).toEqual({ dialect, sql, specific: true }) + } + }) + + test("a SQL Server batch without a separator is named as such, not as a syntax error", () => { + const reason = explainWrite("SELECT a FROM t\nUPDATE t SET a = 1", "sqlserver").reason + expect(reason).toContain("statement keyword UPDATE") + expect(reason).not.toContain("could not read") + }) + + test("an UNKNOWN statement type is named by its first keyword", () => { + expect(explainWrite("ATTACH 'x.db' AS other", "duckdb").reason).not.toContain("UNKNOWN") + // Only known keywords are named; any other first word is the user's text. + expect(explainWrite("acme_secret SELECT 1", "clickhouse").reason).not.toMatch(/ACME_SECRET/i) + }) + + test("names a SQL Server batch keyword", () => { + expect(explainWrite("SELECT exec FROM t", "sqlserver").reason).toContain("statement keyword EXEC") + }) + + test("names a write clause inside a query", () => { + for (const sql of ["WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x", "SELECT * INTO c FROM t"]) { + expect(explainWrite(sql, "postgres")).toEqual({ unreadable: false, reason: expect.stringContaining("write clause") }) + } + }) +}) diff --git a/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts new file mode 100644 index 0000000000..ece856a7a0 --- /dev/null +++ b/packages/opencode/test/altimate/tools/sql-readonly-guard.test.ts @@ -0,0 +1,462 @@ +import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test" +import { Effect } from "effect" +import { PermissionV1 } from "@opencode-ai/core/v1/permission" +import { PermissionNext } from "../../../src/permission/next" +import { SessionID, MessageID } from "../../../src/session/schema" +import { SqlExecuteTool, deniedWriteMessage } from "../../../src/altimate/tools/sql-execute" +import { classifyAndCheck, isScratchSafeWrite } from "../../../src/altimate/tools/sql-classify" +import { hardBlockRefusal, readSql } from "../../../src/altimate/tools/read-only-sql" +import * as Registry from "../../../src/altimate/native/connections/registry" +import { closeScratch } from "../../../src/altimate/native/connections/scratch" +import { initTool } from "../tool-fixture" +import { askFor, denied } from "../../../src/altimate/tool-cli/permissions" + +import { Telemetry } from "../../../src/altimate/telemetry" +import { materialize } from "../../../src/altimate/tools/sql-materialize" +import { checkEngineRead } from "../../../src/altimate/mcp-server/workspace" + +// A read-only agent denies `sql_execute_write`. Reads must never reach that rule, and when a query does, +// the agent must learn why and what to change instead of a raw permission-rule dump it tends to retry. + +const DIALECTS = ["postgres", "snowflake", "bigquery", "duckdb", "sqlite", "mysql", "databricks", "redshift", "sqlserver", "oracle", "clickhouse"] + +// What a read-only agent's denial carries: its catch-all write deny. +const READ_ONLY_RULES = [{ permission: "sql_execute_write", pattern: "*", action: "deny" }] + +const isRead = (sql: string, dialect: string) => { + const result = classifyAndCheck(sql, dialect) + return result.queryType === "read" && !result.blocked +} + +const deniedCtx = (asked: unknown[]) => ({ + sessionID: SessionID.make("ses_readonly_guard"), + messageID: MessageID.make("msg_readonly_guard"), + callID: "", + agent: "analyst", + abort: AbortSignal.any([]), + messages: [] as any[], + metadata: () => {}, + ask: async (request: any) => { + asked.push(request) + if (request.permission === "sql_execute_write") throw new PermissionV1.DeniedError({ ruleset: READ_ONLY_RULES }) + }, +}) + +let previousTelemetry: string | undefined + +beforeAll(() => { + previousTelemetry = process.env.ALTIMATE_TELEMETRY_DISABLED + process.env.ALTIMATE_TELEMETRY_DISABLED = "true" + Registry.setConfigs({ guard_db: { type: "sqlite", path: ":memory:" } as never }) +}) + +afterEach(async () => { + await closeScratch() +}) + +afterAll(() => { + Registry.reset() + if (previousTelemetry === undefined) delete process.env.ALTIMATE_TELEMETRY_DISABLED + else process.env.ALTIMATE_TELEMETRY_DISABLED = previousTelemetry +}) + +describe("reads are classified as reads in every dialect", () => { + const reads: Record = { + "comment with write words": "SELECT id FROM orders -- update later\n/* delete stale rows */", + "leading comment with write words": "-- insert into notes later\nSELECT 1", + "string literal with write words": "SELECT * FROM orders WHERE status = 'DELETED' OR note = 'insert into x'", + "identifiers containing write words": "SELECT update_ts, created_by, deleted_at FROM orders", + "qualified columns named like write keywords": "SELECT o.update, o.delete, o.insert, o.merge FROM orders o", + "three-part names ending in a write keyword": "SELECT s.o.update FROM s.o", + "CTE": "WITH a AS (SELECT 1 AS x), b AS (SELECT x FROM a) SELECT * FROM b", + "EXPLAIN of a read": "EXPLAIN SELECT * FROM orders", + "leading whitespace": "\n\n SELECT 1", + "parenthesized query": "(SELECT 1) UNION ALL (SELECT 2)", + "two reads": "SELECT 1; SELECT 2", + } + // The bundled ClickHouse parser accepts trailing text, so its keyword scan stays strict for dotted names. + const STRICT_DOTTED = new Set(["qualified columns named like write keywords", "three-part names ending in a write keyword"]) + for (const [name, sql] of Object.entries(reads)) { + test(name, () => { + const dialects = STRICT_DOTTED.has(name) ? DIALECTS.filter((d) => d !== "clickhouse") : DIALECTS + expect(dialects.filter((dialect) => !isRead(sql, dialect))).toEqual([]) + }) + } + + test("readSql on ClickHouse refuses dotted statement words too", () => { + expect(() => readSql("SELECT * FROM t AS x.DROP TABLE y", "clickhouse")).toThrow() + expect(() => readSql("SELECT t.alter FROM t", "clickhouse")).toThrow() + expect(readSql("SELECT t.alter FROM t", "postgres")).toBe("SELECT t.alter FROM t") + }) + + test("a dotted word right before a real write clause stays a write", () => { + for (const dialect of ["postgres", "mysql"]) expect(isRead("SELECT a FROM t x.INTO t3", dialect)).toBe(false) + expect(isRead("SELECT a FROM t.into OUTFILE '/tmp/x'", "mysql")).toBe(false) + }) + + test("ClickHouse keeps dotted write keywords as writes, since its parser accepts trailing text", () => { + for (const sql of ["SELECT * FROM a.INTO OUTFILE '/tmp/x'", "SELECT a FROM t x.UPDATE t SET a = 1"]) { + expect(isRead(sql, "clickhouse")).toBe(false) + } + }) + + test("a schema-qualified function named like a statement word is a function call, like any user function", () => { + // Engines read a keyword after a dot as a name. User function calls are reads with or without a qualifier. + for (const dialect of ["sqlserver", "postgres"]) { + for (const sql of ["SELECT run_sql('DELETE FROM t')", "SELECT dbo.run_sql('DELETE FROM t')", "SELECT t.DELETE('x')"]) { + expect(isRead(sql, dialect)).toBe(true) + } + } + expect(isRead("SELECT t.EXEC('DROP TABLE z')", "sqlserver")).toBe(true) + }) + + test("DESCRIBE, SHOW and PRAGMA metadata reads", () => { + for (const sql of ["DESCRIBE orders", "SHOW TABLES", "SHOW COLUMNS FROM orders"]) expect(isRead(sql, "duckdb")).toBe(true) + expect(isRead("PRAGMA table_info('orders')", "sqlite")).toBe(true) + }) +}) + +describe("writes stay writes", () => { + const writes: Record = { + INSERT: "INSERT INTO orders VALUES (1)", + UPDATE: "UPDATE orders SET status = 'x'", + DELETE: "DELETE FROM orders", + MERGE: "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN UPDATE SET v = s.v", + "CREATE TABLE": "CREATE TABLE t (a INT)", + "DROP TABLE": "DROP TABLE orders", + "ALTER TABLE": "ALTER TABLE orders ADD COLUMN c INT", + "COPY INTO": "COPY INTO orders FROM @stage", + "write after a read": "SELECT 1; DELETE FROM orders", + "write hidden after a semicolon on one line": "SELECT * FROM orders;DELETE FROM orders", + "write CTE": "WITH x AS (DELETE FROM orders RETURNING *) SELECT * FROM x", + "SELECT INTO": "SELECT * INTO copy_of_orders FROM orders", + "qualified column beside a real write": "SELECT o.update FROM orders o; UPDATE orders SET a = 1", + "SELECT INTO after a number ending in a dot": "SELECT 1. INTO copy_of_orders FROM orders", + "SELECT INTO after a column and a number ending in a dot": "SELECT o.a, 2. INTO copy_of_orders FROM orders o", + "SELECT INTO after a hex number ending in a dot": "SELECT 0x1.INTO copy_of_orders FROM orders", + "SELECT INTO after a spaced qualifier": "SELECT o. INTO copy_of_orders FROM orders o", + "SELECT INTO after a float with an exponent letter": "SELECT 1.e.INTO copy_of_orders FROM orders", + "write followed by shell residue": "DELETE FROM orders 2>/dev/null", + "unparseable text": "SELECT FROM WHERE (((", + } + for (const [name, sql] of Object.entries(writes)) { + test(name, () => { + expect(DIALECTS.filter((dialect) => isRead(sql, dialect))).toEqual([]) + }) + } +}) + +describe("scratch writes", () => { + test("the scratch catalog prefix is local", () => { + expect(isScratchSafeWrite("CREATE OR REPLACE TABLE scratch.pubs AS SELECT 1 AS x")).toBe(true) + expect(isScratchSafeWrite("CREATE TABLE scratch.main.pubs AS SELECT 1 AS x")).toBe(true) + }) + + test("other catalogs and schemas are not", () => { + expect(isScratchSafeWrite("CREATE TABLE other.pubs AS SELECT 1 AS x")).toBe(false) + expect(isScratchSafeWrite("CREATE TABLE other.main.pubs AS SELECT 1 AS x")).toBe(false) + expect(isScratchSafeWrite("CREATE TABLE scratch.other.pubs AS SELECT 1 AS x")).toBe(false) + }) +}) + +describe("sql_execute on a read-only agent", () => { + const run = async (query: string, warehouse = "guard_db") => { + const tool = await initTool(SqlExecuteTool) + const asked: any[] = [] + const outcome = await tool.execute({ query, warehouse, limit: 10 }, deniedCtx(asked) as any).then( + (result: any) => ({ result, error: undefined as string | undefined }), + (error: Error) => ({ result: undefined, error: error.message }), + ) + return { ...outcome, asked: asked.filter((request) => request.permission === "sql_execute_write") } + } + + test("a qualified column named like a keyword runs without asking", async () => { + const { result, error, asked } = await run("SELECT t.update FROM (SELECT 1 AS \"update\") t", "scratch") + expect(error).toBeUndefined() + expect(asked).toHaveLength(0) + expect(result.output).toMatch(/\b1\b/) + }) + + test("shell residue is named and must be removed; nothing runs", async () => { + const { error } = await run("SELECT 1 AS x 2>/dev/null") + expect(error).toContain("`2>/dev/null`") + expect(error).toContain("Remove it") + expect(error).not.toContain("relevant rules") + }) + + test("unparseable SQL reports the parser's position", async () => { + const { error } = await run("SELECT Order Date FROM orders WHERE Order Date > '2020-01-01'") + expect(error).toMatch(/sqlite SQL parser could not read it \(.*line 1, column \d+/) + expect(error).toContain("Fix the query") + expect(error).not.toContain("....") + }) + + test("a hard block names its rule, or the open quote that made a word count", async () => { + const quote = await run("SELECT * FROM t WHERE note = 'don't truncate'") + expect(quote.error).toContain("blocked for safety") + expect(quote.error).toContain("unterminated") + expect(quote.error).toContain("write a single quote as ''") + expect(quote.asked).toHaveLength(0) + const real = await run("SELECT 1; DROP DATABASE secret_db") + expect(real.error).toContain("statement 2 of 2 is a hard-blocked statement (DROP DATABASE)") + expect(real.error).not.toContain("secret_db") + }) + + test("a write names the statement and suggests a read", async () => { + const { error } = await run("SELECT 1; DELETE FROM orders") + expect(error).toContain("statement 2 of 2 is not a read (DELETE)") + expect(error).not.toContain("FROM orders") + expect(error).toContain("single read") + }) + + test("a scratch batch mixing a write and a read says to split it", async () => { + const { error } = await run("CREATE TABLE items AS SELECT 1 AS v; SELECT * FROM items", "scratch") + expect(error).toContain("statement 1 of 2") + expect(error).toContain("each call without reads") + }) + + test("a scratch write through the scratch catalog runs without asking", async () => { + const { error, asked } = await run("CREATE OR REPLACE TABLE scratch.pubs AS SELECT 1 AS x", "scratch") + expect(error).toBeUndefined() + expect(asked).toHaveLength(0) + }) + + test("a denial that fails an Effect, as the tool bridge runs it, is explained", async () => { + const tool = await initTool(SqlExecuteTool) + // Production runs permission.ask(...).pipe(Effect.orDie) through Effect.runPromise (EffectBridge.promise). + const ctx = { + ...deniedCtx([]), + ask: () => Effect.runPromise(Effect.fail(new PermissionV1.DeniedError({ ruleset: READ_ONLY_RULES })).pipe(Effect.orDie)), + } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("it is not a read (DELETE)") + }) + + test("a denial from the subagent permission path is explained too", async () => { + const tool = await initTool(SqlExecuteTool) + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionNext.DeniedError(READ_ONLY_RULES as any)) } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("it is not a read (DELETE)") + }) + + test("the MCP server and tool CLI write denial is explained, with the --allow-write hint", async () => { + const tool = await initTool(SqlExecuteTool) + const cli = askFor(false) + const ctx = { ...deniedCtx([]), ask: (request: any) => Effect.runPromise(cli(request)) } + const error = await tool + .execute({ query: "SELECT a FROM t 2>/dev/null", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("`2>/dev/null`") + expect(error).toContain("--allow-write") + }) + + test("errors other than a rule denial pass through unchanged", async () => { + const tool = await initTool(SqlExecuteTool) + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new Error("rejected by test")) } + await expect(tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any)).rejects.toThrow( + "rejected by test", + ) + }) +}) + +describe("denied write message branches", () => { + const base = { sql: "SELECT 1", dialects: ["postgres"], jinja: false, mongo: false, scratch: false, warehouseGiven: true } + + test("refusal messages carry their telemetry error class", async () => { + const write = { ...base, sql: "DELETE FROM orders" } + const hard = "DROP DATABASE, DROP SCHEMA and TRUNCATE are blocked for safety." + const scoped = { ...write, readOnly: false } + const hint = denied("sql_execute_write").message + const refusal = async (fn: () => unknown) => { + try { + await fn() + } catch (error) { + if (error instanceof Error) return error.message + throw error + } + throw new Error("Expected a SQL refusal") + } + const tool = await initTool(SqlExecuteTool) + const cases = [ + ["agent", deniedWriteMessage(write), "permission"], + ["pattern rule", deniedWriteMessage(scoped), "permission"], + ["scratch", deniedWriteMessage({ ...write, scratch: true }), "permission"], + ["CLI opening", deniedWriteMessage({ ...write, cli: true }), "permission"], + ["CLI hint", hint, "permission"], + ["CLI refusal with hint", deniedWriteMessage({ ...write, cli: true }) + " " + hint, "permission"], + ["Jinja", deniedWriteMessage({ ...scoped, jinja: true }), "permission"], + ["MongoDB", deniedWriteMessage({ ...scoped, mongo: true }), "permission"], + ["SQL parser error", deniedWriteMessage({ ...scoped, sql: "SELECT Order Date FROM orders" }), "parse_error"], + ["shell residue", deniedWriteMessage({ ...scoped, sql: "SELECT 1 2>/dev/null" }), "parse_error"], + ["open quote", deniedWriteMessage({ ...scoped, sql: "SELECT 'abc" }), "parse_error"], + ["hard block", hardBlockRefusal(hard, "TRUNCATE TABLE orders", "postgres"), "permission"], + ["hard-blocked open quote", hardBlockRefusal(hard, "SELECT 'truncate", "postgres"), "parse_error"], + ["hard-blocked comment", hardBlockRefusal(hard, "SELECT 1 /*! + 1 */", "mysql"), "permission"], + ["sql_check", await refusal(() => readSql(write.sql, "postgres")), "permission"], + ["sql_check statement word", await refusal(() => readSql("SELECT x AS load FROM t", "postgres")), "permission"], + ["sql_check query shape", await refusal(() => readSql("SHOW TABLES", "postgres")), "validation"], + [ + "query_from source", + await refusal(() => tool.execute({ + query_from: { warehouse: "guard_db", sql: write.sql }, + warehouse: "guard_db", + limit: 10, + }, deniedCtx([]) as any)), + "permission", + ], + [ + "sql_materialize", + await refusal(() => materialize({ source_warehouse: "guard_db", sql: write.sql, target_table: "guard_test" })), + "permission", + ], + [ + "MCP workspace", + await refusal(() => checkEngineRead("postgresql_execute_database_query", { query: write.sql })), + "permission", + ], + ] + expect(cases.map(([label, message]) => [label, Telemetry.classifyError(message)])).toEqual( + cases.map(([label, , expected]) => [label, expected]), + ) + }) + + test("Jinja asks for plain SQL", () => { + expect(deniedWriteMessage({ ...base, sql: "SELECT * FROM {{ ref('x') }}", jinja: true })).toContain("Send plain SQL without Jinja") + }) + + test("a MongoDB write asks for a read command", () => { + expect(deniedWriteMessage({ ...base, sql: '{"command":"insertOne"}', mongo: true })).toContain("Use a read command") + }) + + test("a pattern-scoped deny does not claim the agent may only read", () => { + const message = deniedWriteMessage({ ...base, sql: "DROP TABLE stg_tmp", readOnly: false }) + expect(message).toContain("A sql_execute_write permission rule denies it") + expect(message).not.toContain("may only read") + expect(message).toContain("rules allow") + }) + + test("a pattern-rule denial names the patterns the rules allow or ask for", () => { + const message = deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false, permitted: ["INSERT INTO audit*"] }) + expect(message).toContain("they allow or ask for: 'INSERT INTO audit*'") + expect(deniedWriteMessage({ ...base, sql: "DELETE FROM orders", readOnly: false })).not.toContain("allow or ask for") + }) + + test("named rule patterns stay masked in telemetry, even with a trailing backslash or a quote", () => { + const message = deniedWriteMessage({ + ...base, + sql: "DELETE FROM orders", + readOnly: false, + permitted: ["INSERT INTO secret_tbl\\", "UPDATE it's_secret*"], + }) + expect(message).toContain("'INSERT INTO secret_tbl\\\\'") + expect(Telemetry.maskString(message)).not.toMatch(/secret/) + }) + + test("a pattern overridden by a later catch-all deny is not named", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "CREATE TEMP*", action: "allow" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + const error = await tool + .execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("'CREATE TEMP*'") + expect(error).not.toContain("INSERT INTO audit") + }) + + test("a CLI write refusal leads with --allow-write", () => { + const message = deniedWriteMessage({ ...base, sql: "CREATE TABLE t (a int)", cli: true }) + expect(message.indexOf("--allow-write")).toBeGreaterThan(-1) + expect(message.indexOf("--allow-write")).toBeLessThan(message.indexOf("single read")) + }) + + test("an agent deny after a user's ask is still read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "*", pattern: "*", action: "allow" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "*", action: "ask" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("may only read") + }) + + test("a catch-all deny followed by an allow is a rule, not read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "*", pattern: "prod_*", action: "allow" }, + { permission: "sql_execute_write", pattern: "*", action: "deny" }, + { permission: "sql_execute_write", pattern: "INSERT INTO audit*", action: "allow" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + const error = await tool + .execute({ query: "DELETE FROM orders", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("A sql_execute_write permission rule denies it") + // The allowed pattern comes from the denial's own rules. + expect(error).toContain("'INSERT INTO audit*'") + expect(error).not.toContain("'*'") + // Rules for other permissions are not named. + expect(error).not.toContain("prod_") + }) + + test("a pattern-only deny leaves other writes to the default ask, so it is not read-only", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [{ permission: "sql_execute_write", pattern: "DROP*", action: "deny" }] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + await expect( + tool.execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any), + ).rejects.toThrow("A sql_execute_write permission rule denies it") + }) + + test("sql_execute reads the denial's rules to choose the wording", async () => { + const tool = await initTool(SqlExecuteTool) + const ruleset = [ + { permission: "sql_execute_write", pattern: "*", action: "allow" }, + { permission: "sql_execute_write", pattern: "DROP*", action: "deny" }, + ] + const ctx = { ...deniedCtx([]), ask: async () => Promise.reject(new PermissionV1.DeniedError({ ruleset })) } + const error = await tool + .execute({ query: "DROP TABLE stg_tmp", warehouse: "guard_db", limit: 10 }, ctx as any) + .then(() => "", (e: Error) => e.message) + expect(error).toContain("A sql_execute_write permission rule denies it") + // A catch-all allow is not named as a pattern to comply with. + expect(error).not.toContain("allow or ask for") + }) + + test("shell residue without a warehouse does not suggest passing one", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT a FROM t 2>/dev/null", dialects: ["postgres", "snowflake"], warehouseGiven: false }) + expect(message).toContain("shell syntax") + expect(message).not.toContain("pass warehouse") + }) + + test("an unreadable query without a warehouse suggests passing one", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((", dialects: ["postgres", "snowflake"], warehouseGiven: false }) + expect(message).toContain("pass warehouse") + expect(deniedWriteMessage({ ...base, sql: "SELECT FROM WHERE (((" })).not.toContain("pass warehouse") + expect(deniedWriteMessage({ ...base, sql: "DELETE FROM t WHERE ((", readOnly: false })).toContain("may still deny it") + }) + + test("a write in only one reachable dialect suggests passing a warehouse", () => { + const split = { ...base, sql: "SELECT t.update FROM t", dialects: ["postgres", "clickhouse"], warehouseGiven: false } + expect(deniedWriteMessage(split)).toContain("reachable dialects disagree on whether this is a write; pass warehouse") + expect(deniedWriteMessage({ ...split, warehouseGiven: true })).not.toContain("pass warehouse") + // A write in every dialect gets no hint, and on the dbt route a warehouse would also move the query off dbt. + expect(deniedWriteMessage({ ...split, sql: "DELETE FROM t" })).not.toContain("pass warehouse") + expect(deniedWriteMessage({ ...split, dbt: true })).not.toContain("pass warehouse") + }) + + test("the reason comes from a dialect that reads the text when one does", () => { + const message = deniedWriteMessage({ ...base, sql: "SELECT 1 DELETE FROM t", dialects: ["postgres", "sqlserver"], warehouseGiven: false }) + expect(message).toContain("DELETE") + expect(message).not.toContain("could not read") + }) +}) diff --git a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts index 9c8d529ed7..befd20fcfd 100644 --- a/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts +++ b/packages/opencode/test/skill/release-v0.12.9-adversarial.test.ts @@ -424,7 +424,9 @@ describe("v0.12.9 adversarial: runner argument validation and the hard deny end test("a write without allowWrite is refused with the retry hint", async () => { const result = await runner.run("sql_execute", { query: "INSERT INTO t VALUES (1)" }) expect(result.status).toBe("error") - expect(result.output).toBe("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.") + // The refusal says why the query counts as a write, then how to enable writes. + expect(result.output).toContain("Write permission is disabled for this run, and the query counts as a write because it is not a read (INSERT)") + expect(result.output.endsWith("Permission denied: sql_execute_write. Re-run with --allow-write to enable writes.")).toBe(true) }) test("a read that quotes 'drop database' is not refused by the permission gate", async () => {