/**
 * @fileoverview Read-only SQL gate for the DataCanvas primitive. Engine-agnostic
 * pure validators the provider invokes after pulling DuckDB-specific metadata.
 *
 * Four layers of enforcement, each authoritative:
 *
 * 1. **Function deny-list (text scan).** Pre-EXPLAIN regex against the SQL
 *    (string literals stripped) for file/HTTP-reading table functions like
 *    `read_json`, `read_parquet`. These can lower into generic SEQ_SCAN
 *    operators that pass the operator allowlist; catching them by name closes
 *    that bypass.
 * 2. **Single-statement check.** Reject anything other than exactly one
 *    statement parsed by DuckDB. Comment-hidden second statements, Unicode
 *    tricks, and multi-statement smuggling collapse here.
 * 3. **Statement-type check.** Require `SELECT`. DDL, DML, and utility
 *    statements (PRAGMA/ATTACH/COPY/INSTALL/LOAD/SET/EXECUTE) fail to type as
 *    SELECT.
 * 4. **Plan-walk allowlist + denied-function rescan.** Walk the
 *    `EXPLAIN (FORMAT JSON)` tree; reject any operator outside the allowlist
 *    or any string field referencing a deny-listed function.
 *
 * Rejection paths throw `ValidationError` with a structured `data.reason`.
 *
 * @module src/services/canvas/core/sqlGate
 */
/**
 * DuckDB statement-type string. Only `SELECT` is accepted; everything else
 * (DDL, DML, utility) is rejected. Modeled as a string surface rather than an
 * owned enum so the gate matches on whatever DuckDB emits.
 */
export type DuckdbStatementType = string;
/** Subset of statement types the gate permits. */
export declare const ALLOWED_STATEMENT_TYPES: ReadonlySet<DuckdbStatementType>;
/**
 * Reason codes set on `validationError.data.reason` by gate assertions.
 * Consumers can import the {@link SqlGateReason} union to translate gate
 * denials into typed contract reasons without duplicating the strings.
 */
export declare const SQL_GATE_REASONS: {
    readonly multiStatement: "multi_statement";
    readonly nonSelectStatement: "non_select_statement";
    /** SELECT-shaped statement that failed to prepare (unknown column/function/expression). */
    readonly invalidSql: "invalid_sql";
    readonly planOperatorNotAllowed: "plan_operator_not_allowed";
    readonly deniedFunction: "denied_function";
    readonly deniedFunctionInPlan: "denied_function_in_plan";
    readonly identifierEmpty: "identifier_empty";
    readonly identifierShape: "identifier_shape";
    readonly identifierReserved: "identifier_reserved";
    readonly systemCatalogAccess: "system_catalog_access";
};
/** Union of all gate reason strings — see {@link SQL_GATE_REASONS}. */
export type SqlGateReason = (typeof SQL_GATE_REASONS)[keyof typeof SQL_GATE_REASONS];
/**
 * Allowlist of read-only operator names that can appear in an EXPLAIN plan.
 * Anything outside this set causes rejection. Notable exclusions:
 *
 * - `READ_CSV`, `READ_PARQUET`, `READ_JSON` — bypass canvas, read external files.
 * - `INSERT`, `UPDATE`, `DELETE`, `MERGE_INTO`, `CREATE_*`, `DROP`, `ALTER` — writes.
 * - `COPY_TO_FILE`, `BATCH_COPY_TO_FILE`, `COPY_DATABASE` — write a SELECT to a file/db.
 * - `ATTACH`, `DETACH`, `LOAD`, `PRAGMA`, `SET`, `SET_VARIABLE`, `RESET`, `TRANSACTION`,
 *   `EXECUTE`, `PREPARE`, `VACUUM`, `EXPORT`, `EXPLAIN_ANALYZE`, `CREATE_SECRET` — utility/system.
 * - `INOUT_FUNCTION` — table-valued function lowering (read_json/read_parquet/...);
 *   gated by the function deny-list rather than the operator allowlist.
 *
 * Source pinned against `PhysicalOperatorToString` in DuckDB v1.5.2:
 * https://github.com/duckdb/duckdb/blob/v1.5.2/src/common/enums/physical_operator_type.cpp
 */
export declare const ALLOWED_PLAN_OPERATORS: ReadonlySet<string>;
/**
 * External-data table functions (files, HTTP, S3, lakehouse formats). These
 * lower into generic scan operators that pass the operator allowlist, so the
 * text-scan and plan-rescan defenses in this module catch them by name
 * regardless of how DuckDB lowers them.
 */
export declare const DENIED_TABLE_FUNCTIONS: ReadonlySet<string>;
/**
 * Layer 1: pre-EXPLAIN function deny-list. Scans the SQL (string literals
 * stripped) for calls to any function in {@link DENIED_TABLE_FUNCTIONS} or the
 * `pragma_*` namespace so a malicious `read_json('/etc/passwd')` or
 * `pragma_table_info('t')` is rejected before reaching the planner.
 */
export declare function assertNoDeniedFunctions(sql: string): void;
/**
 * Optional gate layer: reject references to system catalog namespaces.
 *
 * Enable via `QueryOptions.denySystemCatalogs` or
 * `RegisterViewOptions.denySystemCatalogs` on servers that use a hidden shared
 * canvas where handle possession is the access boundary. When enabled, any
 * reference to `information_schema`, `pg_catalog`, `sqlite_master`, or
 * `duckdb_<name>()` throws `ValidationError` with
 * `data.reason: 'system_catalog_access'`.
 *
 * Callers strip comments and string literals before this scan (identical
 * pre-processing to {@link assertNoDeniedFunctions}).
 */
export declare function assertNoSystemCatalogs(sql: string): void;
/**
 * Layers 2-4. Throws on the first violation. Layer 1
 * ({@link assertNoDeniedFunctions}) runs separately before `extractStatements`.
 */
export declare function assertReadOnlyQuery(input: {
    /** Number of statements DuckDB extracted from the user-supplied SQL. */
    statementCount: number;
    /** DuckDB statement type for the (single) prepared statement. */
    statementType: DuckdbStatementType;
    /** Parsed `EXPLAIN (FORMAT JSON)` payload. */
    planJson: unknown;
}): void;
/**
 * Layers 2-3: validate statement count and type before EXPLAIN. Non-SELECT
 * statements (ATTACH/PRAGMA/COPY/INSTALL/...) fail here with a structured
 * ValidationError rather than a confusing parser error from EXPLAIN itself.
 */
export declare function assertSelectOnly(input: {
    statementCount: number;
    statementType: DuckdbStatementType;
}): void;
/**
 * Layer 4: walk the plan tree and reject any operator outside the allowlist
 * or any deny-listed table function smuggled into a generic scan operator.
 */
export declare function assertPlanReadOnly(planJson: unknown): void;
/**
 * Returns operator names not in `ALLOWED_PLAN_OPERATORS`. Exported for
 * fixture-driven tests that want to inspect the gate's view without throwing.
 * Use {@link collectPlanViolations} to also surface deny-listed function
 * references in scan-operator metadata.
 */
export declare function collectDisallowedOperators(planJson: unknown): Set<string>;
/**
 * Combined plan-walk: disallowed operators and deny-listed table-function
 * references in string-valued fields, returned separately so callers can word
 * errors appropriately.
 */
export declare function collectPlanViolations(planJson: unknown): {
    offending: Set<string>;
    deniedFunctions: Set<string>;
};
/**
 * Allowed shape for canvas table/column names. SQL identifier convention:
 * letter/underscore start, letters/digits/underscores after, max 63 chars
 * (PostgreSQL/DuckDB cap). Exported so consumers can reuse it in Zod schemas
 * (`z.string().regex(CANVAS_IDENTIFIER_REGEX)`).
 */
export declare const CANVAS_IDENTIFIER_REGEX: RegExp;
/** Validate a canvas table or column name. Throws `ValidationError` on rejection. */
export declare function assertValidIdentifier(value: string, kind: 'table' | 'column'): void;
/**
 * Double-quote-escape an identifier for SQL embedding. Validate via
 * {@link assertValidIdentifier} first — this helper only escapes, it does not
 * check shape.
 */
export declare function quoteIdentifier(value: string): string;
//# sourceMappingURL=sqlGate.d.ts.map