sql-guard 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * sql-guard
+ *
+ * Validate AI-generated PostgreSQL queries against explicit table allowlists.
+ * This package parses SQL into an AST and denies anything outside your policy.
+ *
+ * @example
+ * ```typescript
+ * import { validate, assertSafeSql, ErrorCode } from 'sql-guard';
+ *
+ * const policy = {
+ *   allowedTables: ['public.users', 'public.orders'],
+ *   allowedFunctions: ['count', 'lower'],
+ * };
+ *
+ * // Non-throwing validation
+ * const result = validate('SELECT * FROM public.users', policy);
+ * if (!result.ok) {
+ *   console.log('Denied:', result.errorCode);
+ *   console.log('Violations:', result.violations);
+ * }
+ *
+ * // Throwing validation
+ * assertSafeSql('SELECT lower(u.email) FROM public.users u', policy);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ErrorCode, SqlValidationError } from './types/public';
+import type { Policy, ValidationResult } from './types/public';
+/**
+ * Validates SQL against a policy.
+ *
+ * Parses the SQL and checks it against the policy rules. Returns a result object
+ * indicating whether the SQL is allowed and any violations found.
+ *
+ * This function never throws. All errors are captured in the returned ValidationResult.
+ *
+ * @param sql - The SQL query to validate
+ * @param policy - The policy defining allowed tables, statements, etc.
+ * @returns ValidationResult with ok status and any violations
+ *
+ * @example
+ * ```typescript
+ * const result = validate('SELECT * FROM public.users', {
+ *   allowedTables: ['public.users'],
+ *   allowedFunctions: ['count']
+ * });
+ *
+ * if (result.ok) {
+ *   console.log('Query is safe');
+ * } else {
+ *   console.log('Blocked:', result.errorCode);
+ *   console.log('Reason:', result.violations[0]?.message);
+ * }
+ * ```
+ */
+export declare function validate(sql: string, policy: Policy): ValidationResult;
+/**
+ * Validates SQL and throws SqlValidationError if invalid.
+ *
+ * Same as {@link validate} but throws an exception on validation failure
+ * instead of returning a result object. Useful for fail-fast scenarios.
+ *
+ * @param sql - The SQL query to validate
+ * @param policy - The policy defining allowed tables, statements, etc.
+ * @throws SqlValidationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   assertSafeSql('SELECT * FROM public.users', policy);
+ *   // Query is safe, proceed with execution
+ * } catch (err) {
+ *   if (err instanceof SqlValidationError) {
+ *     console.error('Query blocked:', err.code);
+ *   }
+ * }
+ * ```
+ */
+export declare function assertSafeSql(sql: string, policy: Policy): void;
+export { ErrorCode, SqlValidationError };
+export type { Policy, ValidationResult, TableIdentifierMatching } from './types/public';
+export type { Violation } from './types/public';
+export { parseSql } from './parser/adapter';
+export type { ParseResult, ParsedStatement, TableReference, FunctionCall } from './parser/types';
+export { normalizeTableReference, isTableAllowed } from './normalize/identifier';
+export type { NormalizedTable, NormalizationResult } from './normalize/identifier';
+export { isStatementAllowed, checkMultiStatementPolicy } from './policy/statement';
+export type { StatementCheckResult, StatementType } from './policy/statement';
+export { extractAllTables } from './analysis/relations';
+export { extractAllFunctions } from './analysis/functions';
+export { checkFunctionsAllowed } from './policy/function';
+export type { FunctionCheckResult } from './policy/function';
+export { validateAgainstPolicy } from './policy/engine';
+export type { EngineResult } from './policy/engine';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAS/D;AAGD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;AACzC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACxF,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACjF,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/normalize/identifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Identifier Normalization
+ *
+ * Utilities for normalizing table references and checking them against allowlists.
+ * Handles schema qualification, quoted identifiers, and resolver callbacks.
+ *
+ * @module
+ */
+import type { Policy, TableIdentifierMatching } from '../types/public';
+import type { TableReference } from '../parser/types';
+/**
+ * A normalized, schema-qualified table reference.
+ */
+export interface NormalizedTable {
+    /** Schema name (e.g., 'public') */
+    schema: string;
+    /** Table name */
+    name: string;
+    /** Fully qualified name in format 'schema.name' */
+    fullyQualified: string;
+}
+/**
+ * Result of normalizing a table reference.
+ */
+export interface NormalizationResult {
+    /** Whether normalization succeeded */
+    success: boolean;
+    /** The normalized table (only present if success is true) */
+    table?: NormalizedTable;
+    /** Error message (only present if success is false) */
+    error?: string;
+}
+/**
+ * Normalize a table reference using the policy's resolver if needed.
+ *
+ * For schema-qualified references (e.g., `public.users`), extracts the schema
+ * and name directly. For unqualified references (e.g., `users`), uses the
+ * policy's resolver function to map to a fully qualified name.
+ *
+ * @param ref - The table reference from the parser
+ * @param policy - The policy containing the resolver
+ * @returns NormalizationResult with the normalized table or an error
+ */
+export declare function normalizeTableReference(ref: TableReference, policy: Policy, mode?: TableIdentifierMatching): NormalizationResult;
+/**
+ * Check if a normalized table is in the allowlist.
+ *
+ * Performs case-insensitive comparison against the allowed tables.
+ *
+ * @param normalized - The normalized table to check
+ * @param allowedTables - Iterable of allowed table names (schema-qualified)
+ * @returns True if the table is allowed
+ */
+export declare function isTableAllowed(normalized: NormalizedTable, allowedTables: Iterable<string>, mode?: TableIdentifierMatching): boolean;
+//# sourceMappingURL=identifier.d.ts.map

package/dist/normalize/identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.d.ts","sourceRoot":"","sources":["../../src/normalize/identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,uBAAoE,GACzE,mBAAmB,CAmDrB;AAcD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,eAAe,EAC3B,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC/B,IAAI,GAAE,uBAAkC,GACvC,OAAO,CAcT"}

package/dist/normalize/qualified-name.d.ts

@@ -0,0 +1,9 @@
+import type { TableIdentifierMatching } from "../types/public";
+export interface QualifiedNameParts {
+    schema: string;
+    name: string;
+    fullyQualified: string;
+}
+export declare function parseQualifiedName(value: unknown, mode?: TableIdentifierMatching): QualifiedNameParts | null;
+export declare function canonicalizeIdentifier(value: string, mode: TableIdentifierMatching): string;
+//# sourceMappingURL=qualified-name.d.ts.map

package/dist/normalize/qualified-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualified-name.d.ts","sourceRoot":"","sources":["../../src/normalize/qualified-name.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,uBAAkC,GACvC,kBAAkB,GAAG,IAAI,CA2B3B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,uBAAuB,GAC5B,MAAM,CAGR"}

package/dist/parser/adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SQL Parser Adapter
+ *
+ * Wraps node-sql-parser to parse PostgreSQL SQL into an AST.
+ * Extracts tables and functions for policy validation.
+ *
+ * @module
+ */
+import { ParseResult } from './types';
+/**
+ * Parse a SQL string into an AST.
+ *
+ * Parses the SQL and extracts tables, functions, and statement types.
+ * Returns a structured result that can be used for policy validation.
+ *
+ * @param sql - The SQL query to parse
+ * @param dialect - SQL dialect to use (defaults to 'postgresql')
+ * @returns ParseResult with success status and parsed statements or error info
+ *
+ * @example
+ * ```typescript
+ * const result = parseSql('SELECT * FROM public.users');
+ * if (result.success) {
+ *   console.log('Tables:', result.statements[0].tables);
+ *   console.log('Functions:', result.statements[0].functions);
+ * }
+ * ```
+ */
+export declare function parseSql(sql: string, dialect?: 'postgresql'): ParseResult;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/parser/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/parser/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAC;AAMvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAA2B,GAAG,WAAW,CAmBvF"}

package/dist/parser/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Types for parsed SQL statements, tables, and function calls.
+ * These types represent the AST (Abstract Syntax Tree) produced by the SQL parser.
+ *
+ * @module
+ */
+/**
+ * A parsed SQL statement with extracted metadata.
+ * Contains the statement type, referenced tables, and function calls.
+ */
+export interface ParsedStatement {
+    /** The type of SQL statement (select, insert, update, delete, or unknown) */
+    type: 'select' | 'insert' | 'update' | 'delete' | 'unknown';
+    /** Tables referenced in this statement */
+    tables: TableReference[];
+    /** Function calls in this statement */
+    functions: FunctionCall[];
+    /** Raw AST from the parser (internal use) */
+    raw: unknown;
+}
+/**
+ * Reference to a table in a SQL query.
+ * May be schema-qualified or unqualified.
+ */
+export interface TableReference {
+    /** Schema name (e.g., 'public'). Undefined for unqualified tables. */
+    schema?: string;
+    /** Table name */
+    name: string;
+    /** Table alias, if specified (e.g., 'u' in `FROM users u`) */
+    alias?: string;
+    /** Source location in the SQL string */
+    location?: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * Reference to a function call in a SQL query.
+ */
+export interface FunctionCall {
+    /** Function name */
+    name: string;
+    /** Schema name (e.g., 'pg_catalog'). Undefined for unqualified functions. */
+    schema?: string;
+    /** Source location in the SQL string */
+    location?: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * Result of parsing a SQL string.
+ * On success, contains the parsed statements.
+ * On failure, contains error information.
+ */
+export interface ParseResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** Parsed statements (empty if success is false) */
+    statements: ParsedStatement[];
+    /** Error information (only present if success is false) */
+    error?: {
+        /** Error message from the parser */
+        message: string;
+        /** Location where the error occurred, if available */
+        location?: {
+            line: number;
+            column: number;
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/parser/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/parser/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5D,0CAA0C;IAC1C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,uCAAuC;IACvC,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE;QACN,oCAAoC;QACpC,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,QAAQ,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7C,CAAC;CACH"}

package/dist/policy/compile-policy.d.ts

@@ -0,0 +1,20 @@
+import { ErrorCode } from '../types/public';
+import type { Policy, TableIdentifierMatching, Violation } from '../types/public';
+export interface CompiledPolicy {
+    allowedTables: Set<string>;
+    allowedFunctionsUnqualified: Set<string>;
+    allowedFunctionsQualified: Set<string>;
+    tableIdentifierMatching: TableIdentifierMatching;
+}
+type CompilePolicyResult = {
+    success: true;
+    compiled: CompiledPolicy;
+} | {
+    success: false;
+    errorCode: ErrorCode.INVALID_POLICY;
+    violation: Violation;
+};
+export declare function compilePolicy(policy: Policy): CompilePolicyResult;
+export declare function canonicalizeQualifiedName(value: unknown, mode?: TableIdentifierMatching): string | null;
+export {};
+//# sourceMappingURL=compile-policy.d.ts.map

package/dist/policy/compile-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-policy.d.ts","sourceRoot":"","sources":["../../src/policy/compile-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,2BAA2B,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,yBAAyB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED,KAAK,mBAAmB,GACpB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAC3C;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC,cAAc,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAElF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAwDjE;AA2BD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,uBAAkC,GACvC,MAAM,GAAG,IAAI,CAGf"}

package/dist/policy/engine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Policy Validation Engine
+ *
+ * Core validation logic that orchestrates parsing, policy compilation,
+ * and violation detection.
+ *
+ * @module
+ */
+import { ErrorCode } from '../types/public';
+import type { Policy, ValidationResult, Violation } from '../types/public';
+/**
+ * Internal result type used during validation.
+ */
+export interface EngineResult {
+    ok: boolean;
+    violations: Violation[];
+    errorCode?: ErrorCode;
+}
+/**
+ * Validate a SQL query against a policy.
+ *
+ * This is the main validation function used by {@link validate}.
+ * It compiles the policy, parses the SQL, and checks all constraints.
+ *
+ * @param sql - The SQL query to validate
+ * @param policy - The policy to validate against
+ * @returns ValidationResult indicating success or failure with violations
+ */
+export declare function validateAgainstPolicy(sql: string, policy: Policy): ValidationResult;
+//# sourceMappingURL=engine.d.ts.map

package/dist/policy/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/policy/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAID;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CA0JnF"}

package/dist/policy/fail-closed.d.ts

@@ -0,0 +1,8 @@
+import { ErrorCode } from '../types/public';
+export interface UnsupportedCheckResult {
+    supported: boolean;
+    errorCode?: ErrorCode.UNSUPPORTED_SQL_FEATURE;
+    errorMessage?: string;
+}
+export declare function checkUnsupportedFeatures(ast: unknown): UnsupportedCheckResult;
+//# sourceMappingURL=fail-closed.d.ts.map

package/dist/policy/fail-closed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-closed.d.ts","sourceRoot":"","sources":["../../src/policy/fail-closed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC,uBAAuB,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAoCD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAsD7E"}

package/dist/policy/function.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Function Policy Validation
+ *
+ * Validates function calls against policy allowlists.
+ *
+ * @module
+ */
+import { FunctionCall } from '../parser/types';
+import { ErrorCode } from '../types/public';
+import type { CompiledPolicy } from './compile-policy';
+import type { Policy } from '../types/public';
+/**
+ * Result of checking if functions are allowed.
+ */
+export interface FunctionCheckResult {
+    /** Whether all functions are allowed */
+    allowed: boolean;
+    /** Error code if any function is not allowed */
+    errorCode?: ErrorCode;
+    /** Human-readable error message */
+    errorMessage?: string;
+    /** List of disallowed functions */
+    violations: Array<{
+        name: string;
+        schema?: string;
+    }>;
+}
+/**
+ * Check if functions in a parsed statement are allowed by the policy.
+ *
+ * @param functions - Array of function calls from the parser
+ * @param policy - The policy containing allowed functions
+ * @returns FunctionCheckResult indicating if all functions are allowed
+ */
+export declare function checkFunctionsAllowed(functions: FunctionCall[], policy: Policy): FunctionCheckResult;
+/**
+ * Check if functions are allowed using a compiled policy.
+ *
+ * @param functions - Array of function calls from the parser
+ * @param policy - The compiled policy containing function allowlists
+ * @returns FunctionCheckResult indicating if all functions are allowed
+ */
+export declare function checkFunctionsAllowedCompiled(functions: FunctionCall[], policy: CompiledPolicy): FunctionCheckResult;
+//# sourceMappingURL=function.d.ts.map

package/dist/policy/function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.d.ts","sourceRoot":"","sources":["../../src/policy/function.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,EAAE,MAAM,GACb,mBAAmB,CAGrB;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,EAAE,cAAc,GACrB,mBAAmB,CAKrB"}

package/dist/policy/statement.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Statement Policy Validation
+ *
+ * Validates SQL statement types against policy restrictions.
+ *
+ * @module
+ */
+import { ParsedStatement } from '../parser/types';
+import { ErrorCode } from '../types/public';
+import type { Policy } from '../types/public';
+/**
+ * Result of checking if a statement type is allowed.
+ */
+export interface StatementCheckResult {
+    /** Whether the statement type is allowed */
+    allowed: boolean;
+    /** Error code if not allowed */
+    errorCode?: ErrorCode;
+    /** Human-readable error message */
+    errorMessage?: string;
+}
+/**
+ * Supported SQL statement types.
+ */
+export type StatementType = 'select' | 'insert' | 'update' | 'delete';
+/**
+ * Check if a statement type is allowed by the policy.
+ *
+ * @param statement - The parsed statement to check
+ * @param policy - The policy defining allowed statement types
+ * @returns StatementCheckResult indicating if the statement is allowed
+ */
+export declare function isStatementAllowed(statement: ParsedStatement, policy: Policy): StatementCheckResult;
+/**
+ * Check if multiple statements are allowed by the policy.
+ *
+ * @param statements - Array of parsed statements
+ * @param policy - The policy defining whether multiple statements are allowed
+ * @returns StatementCheckResult indicating if multiple statements are allowed
+ */
+export declare function checkMultiStatementPolicy(statements: ParsedStatement[], policy: Policy): StatementCheckResult;
+//# sourceMappingURL=statement.d.ts.map

package/dist/policy/statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.d.ts","sourceRoot":"","sources":["../../src/policy/statement.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,MAAM,GACb,oBAAoB,CAsBtB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,MAAM,GACb,oBAAoB,CAYtB"}

package/dist/types/public.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Error codes returned by the validator when SQL queries fail validation.
+ * Used to identify the specific reason a query was rejected.
+ *
+ * @example
+ * ```typescript
+ * import { validate, ErrorCode } from 'sql-guard';
+ *
+ * const result = validate('SELECT * FROM secret_table', { allowedTables: ['public.users'] });
+ * if (result.errorCode === ErrorCode.TABLE_NOT_ALLOWED) {
+ *   console.log('Query tried to access unauthorized table');
+ * }
+ * ```
+ */
+export declare enum ErrorCode {
+    /** SQL could not be parsed into an AST */
+    PARSE_ERROR = "PARSE_ERROR",
+    /** Parsed SQL contains features outside the supported subset (fail closed) */
+    UNSUPPORTED_SQL_FEATURE = "UNSUPPORTED_SQL_FEATURE",
+    /** A referenced table is not in the policy allowlist */
+    TABLE_NOT_ALLOWED = "TABLE_NOT_ALLOWED",
+    /** Statement type (e.g., INSERT, UPDATE) is not allowed by the policy */
+    STATEMENT_NOT_ALLOWED = "STATEMENT_NOT_ALLOWED",
+    /** A function call is not in the policy allowlist */
+    FUNCTION_NOT_ALLOWED = "FUNCTION_NOT_ALLOWED",
+    /** Query contains multiple statements while allowMultiStatement is disabled */
+    MULTI_STATEMENT_DISABLED = "MULTI_STATEMENT_DISABLED",
+    /** Policy configuration is invalid */
+    INVALID_POLICY = "INVALID_POLICY"
+}
+/**
+ * Controls how table identifiers are matched against policy allowlists.
+ *
+ * - `strict`: exact case-sensitive matching (security-first default).
+ * - `caseInsensitive`: case-insensitive matching.
+ */
+export type TableIdentifierMatching = "strict" | "caseInsensitive";
+/**
+ * Policy configuration that defines what SQL is allowed.
+ * Used with {@link validate} and {@link assertSafeSql} to enforce query restrictions.
+ *
+ * @example
+ * ```typescript
+ * const policy: Policy = {
+ *   allowedTables: ['public.users', 'public.orders'],
+ *   allowedStatements: ['select'],
+ *   allowedFunctions: ['count', 'lower'],
+ *   allowMultiStatement: false,
+ *   resolver: (name) => name === 'users' ? 'public.users' : null
+ * };
+ * ```
+ */
+export interface Policy {
+    /**
+     * List of allowed tables in schema-qualified format (e.g., 'public.users').
+     * All tables referenced in SQL must be in this list.
+     * @remarks Required field
+     */
+    allowedTables: string[];
+    /**
+     * List of allowed SQL statement types.
+     * Defaults to `['select']` if not specified.
+     * @default ['select']
+     */
+    allowedStatements?: ("select" | "insert" | "update" | "delete")[];
+    /**
+     * Whether to allow multiple statements in a single query (e.g., `SELECT 1; SELECT 2`).
+     * Defaults to `false` for security.
+     * @default false
+     */
+    allowMultiStatement?: boolean;
+    /**
+     * List of allowed functions. Functions not in this list will be rejected.
+     * Use unqualified names (e.g., 'lower') to match unqualified calls.
+     * Use qualified names (e.g., 'pg_catalog.current_database') to match qualified calls.
+     * @default []
+     */
+    allowedFunctions?: string[];
+    /**
+     * Table identifier matching mode used for allowlist checks.
+     * `strict` is the secure default and preserves case distinctions.
+     * `caseInsensitive` enables case-insensitive behavior.
+     * @default 'strict'
+     */
+    tableIdentifierMatching?: TableIdentifierMatching;
+    /**
+     * Optional resolver function to map unqualified table names to schema-qualified names.
+     * Return the fully qualified table name (e.g., 'public.users') or null to deny.
+     *
+     * @example
+     * ```typescript
+     * resolver: (name) => {
+     *   if (name === 'users') return 'public.users';
+     *   if (name === 'orders') return 'public.orders';
+     *   return null; // Deny unknown tables
+     * }
+     * ```
+     */
+    resolver?: (unqualified: string) => string | null;
+}
+/**
+ * Result of validating a SQL query against a policy.
+ * Returned by {@link validate}.
+ *
+ * @example
+ * ```typescript
+ * const result = validate('SELECT * FROM public.users', policy);
+ * if (result.ok) {
+ *   console.log('Query is safe');
+ * } else {
+ *   console.log('Violations:', result.violations);
+ *   console.log('Error code:', result.errorCode);
+ * }
+ * ```
+ */
+export interface ValidationResult {
+    /** Whether the SQL passed all policy checks */
+    ok: boolean;
+    /** List of violations found during validation (empty if ok is true) */
+    violations: Violation[];
+    /** Error code categorizing why validation failed (undefined if ok is true) */
+    errorCode?: ErrorCode;
+}
+/**
+ * A single violation found during SQL validation.
+ * Part of the {@link ValidationResult.violations} array.
+ */
+export interface Violation {
+    /** Type of violation */
+    type: "table" | "statement" | "function" | "parse" | "unsupported" | "policy";
+    /** Human-readable description of the violation */
+    message: string;
+    /**
+     * Source location where the violation occurred, if available.
+     * Line and column numbers are 1-indexed.
+     */
+    location?: {
+        line?: number;
+        column?: number;
+    };
+}
+/**
+ * Error thrown by {@link assertSafeSql} when validation fails.
+ * Extends the standard Error class with additional context.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   assertSafeSql('SELECT * FROM secret_table', policy);
+ * } catch (err) {
+ *   if (err instanceof SqlValidationError) {
+ *     console.log('Error code:', err.code);
+ *     console.log('Violations:', err.violations);
+ *   }
+ * }
+ * ```
+ */
+export declare class SqlValidationError extends Error {
+    /** Error code indicating the type of validation failure */
+    readonly code: ErrorCode;
+    /** Detailed violations that caused the failure */
+    readonly violations: Violation[];
+    /**
+     * Creates a new SqlValidationError.
+     * @param message - Error message
+     * @param code - Error code categorizing the failure
+     * @param violations - Array of specific violations found
+     */
+    constructor(message: string, 
+    /** Error code indicating the type of validation failure */
+    code: ErrorCode, 
+    /** Detailed violations that caused the failure */
+    violations: Violation[]);
+}
+//# sourceMappingURL=public.d.ts.map

package/dist/types/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/types/public.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oBAAY,SAAS;IACnB,0CAA0C;IAC1C,WAAW,gBAAgB;IAC3B,8EAA8E;IAC9E,uBAAuB,4BAA4B;IACnD,wDAAwD;IACxD,iBAAiB,sBAAsB;IACvC,yEAAyE;IACzE,qBAAqB,0BAA0B;IAC/C,qDAAqD;IACrD,oBAAoB,yBAAyB;IAC7C,+EAA+E;IAC/E,wBAAwB,6BAA6B;IACrD,sCAAsC;IACtC,cAAc,mBAAmB;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,iBAAiB,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IAElE;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAC;IAElD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACnD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC9E,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IASzC,2DAA2D;aAC3C,IAAI,EAAE,SAAS;IAC/B,kDAAkD;aAClC,UAAU,EAAE,SAAS,EAAE;IAXzC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM;IACf,2DAA2D;IAC3C,IAAI,EAAE,SAAS;IAC/B,kDAAkD;IAClC,UAAU,EAAE,SAAS,EAAE;CAK1C"}