proxql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Result of a SQL validation check.
+ *
+ * Can be used in boolean context:
+ * ```typescript
+ * const result = validate("SELECT * FROM users");
+ * if (result) {
+ *   // Query is safe
+ * }
+ * ```
+ */
+declare class ValidationResult {
+    /** Whether the query passed all validation checks */
+    readonly isSafe: boolean;
+    /** Explanation if the query was blocked (undefined if safe) */
+    readonly reason?: string;
+    /** The type of SQL statement (SELECT, INSERT, DROP, etc.) */
+    readonly statementType?: string;
+    /** Tables referenced in the query */
+    readonly tables: string[];
+    private constructor();
+    /**
+     * Create a safe validation result.
+     */
+    static safe(meta?: {
+        statementType?: string;
+        tables?: string[];
+    }): ValidationResult;
+    /**
+     * Create an unsafe validation result with a reason.
+     */
+    static unsafe(reason: string, meta?: {
+        statementType?: string;
+        tables?: string[];
+    }): ValidationResult;
+    /**
+     * Allow using ValidationResult in boolean context.
+     * Note: This is for documentation purposes; JS doesn't support operator overloading.
+     * Use result.isSafe directly.
+     */
+    valueOf(): boolean;
+    toString(): string;
+}
+
+/**
+ * Severity levels for security rules.
+ */
+declare enum RuleSeverity {
+    /** Informational findings (e.g., metadata access) */
+    LOW = "LOW",
+    /** Suspicious patterns that may indicate attacks */
+    MEDIUM = "MEDIUM",
+    /** Likely malicious patterns */
+    HIGH = "HIGH",
+    /** Definitely malicious, immediate threat */
+    CRITICAL = "CRITICAL"
+}
+/**
+ * Options for SecurityConfig.
+ */
+interface SecurityConfigOptions {
+    /** Enable/disable all security rules (default: true) */
+    enabled?: boolean;
+    /** Minimum severity to check (default: HIGH) */
+    minimumSeverity?: RuleSeverity | keyof typeof RuleSeverity;
+    /** Rule IDs to skip */
+    disabledRules?: Set<string> | string[];
+    /** If set, ONLY run these rules (whitelist mode) */
+    enabledRules?: Set<string> | string[] | null;
+    /** Whether LOW severity findings should block queries (default: false) */
+    failOnLow?: boolean;
+}
+/**
+ * Configuration for security rule behavior.
+ */
+declare class SecurityConfig {
+    /** Whether security checks are enabled */
+    readonly enabled: boolean;
+    /** Minimum severity level to check */
+    readonly minimumSeverity: RuleSeverity;
+    /** Rule IDs that are disabled */
+    readonly disabledRules: Set<string>;
+    /** If set, only these rules run (whitelist mode) */
+    readonly enabledRules: Set<string> | null;
+    /** Whether LOW severity should block queries */
+    readonly failOnLow: boolean;
+    constructor(options?: SecurityConfigOptions);
+    /**
+     * Check if a rule should run based on this configuration.
+     */
+    shouldRunRule(ruleId: string, severity: RuleSeverity): boolean;
+    /**
+     * Check if a finding at this severity should fail validation.
+     */
+    shouldFail(severity: RuleSeverity): boolean;
+}
+
+/**
+ * Validation mode.
+ */
+type Mode = 'read_only' | 'write_safe' | 'custom';
+/**
+ * Options for creating a Validator.
+ */
+interface ValidatorOptions {
+    /** Validation mode (default: "read_only") */
+    mode?: Mode;
+    /** Optional list of table names that can be accessed */
+    allowedTables?: string[];
+    /** For custom mode: statements to allow */
+    allowedStatements?: string[];
+    /** For custom mode: statements to block */
+    blockedStatements?: string[];
+    /** SQL dialect for parsing */
+    dialect?: string;
+    /** Security rule configuration (true/false/SecurityConfig/SecurityConfigOptions) */
+    securityConfig?: boolean | SecurityConfig | SecurityConfigOptions;
+}
+/**
+ * SQL query validator.
+ *
+ * For repeated validations with the same configuration, create a Validator
+ * instance rather than calling validate() each time.
+ *
+ * @example
+ * ```typescript
+ * const validator = new Validator({
+ *   mode: "read_only",
+ *   allowedTables: ["products", "categories"]
+ * });
+ *
+ * validator.validate("SELECT * FROM products").isSafe  // true
+ * validator.validate("SELECT * FROM users").isSafe     // false
+ * ```
+ */
+declare class Validator {
+    private readonly mode;
+    private readonly allowedTables;
+    private readonly allowedStatements;
+    private readonly blockedStatements;
+    private readonly dialect;
+    private readonly securityConfig;
+    private readonly parser;
+    constructor(options?: ValidatorOptions);
+    private initAllowedStatements;
+    private initBlockedStatements;
+    /**
+     * Validate a SQL query.
+     */
+    validate(sql: string): ValidationResult;
+    private mapDialect;
+    private getStatementType;
+    private checkStatementType;
+    private checkTables;
+    private extractTables;
+    private extractAllTables;
+    private walkAst;
+}
+
+/**
+ * ProxQL - The Database Firewall for AI Agents
+ *
+ * A SQL validation library that blocks destructive queries from LLM-generated SQL.
+ *
+ * @example
+ * ```typescript
+ * import proxql from 'proxql';
+ *
+ * // Simple validation (read_only mode by default)
+ * proxql.validate("SELECT * FROM users").isSafe  // true
+ * proxql.validate("DROP TABLE users").isSafe     // false
+ *
+ * // Quick boolean check
+ * proxql.isSafe("SELECT * FROM users")  // true
+ *
+ * // With custom configuration
+ * const { Validator } = proxql;
+ * const v = new Validator({ mode: "read_only", allowedTables: ["products"] });
+ * v.validate("SELECT * FROM products").isSafe  // true
+ * v.validate("SELECT * FROM users").isSafe     // false
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for the validate() and isSafe() functions.
+ */
+interface ValidateOptions {
+    /** Validation mode - "read_only", "write_safe", or "custom" */
+    mode?: 'read_only' | 'write_safe' | 'custom';
+    /** Optional list of table names that can be accessed */
+    allowedTables?: string[];
+    /** SQL dialect for parsing ('postgres', 'mysql', 'snowflake', etc.) */
+    dialect?: string;
+    /**
+     * Security rule configuration:
+     * - true (default): Enable default rules (HIGH+ severity)
+     * - false: Disable security rules
+     * - SecurityConfig or SecurityConfigOptions: Custom security configuration
+     */
+    security?: boolean | SecurityConfig | SecurityConfigOptions;
+}
+/**
+ * Validate a SQL query.
+ *
+ * This is the simplest way to use ProxQL. For repeated validations with the
+ * same configuration, create a Validator instance for better performance.
+ *
+ * @param sql - The SQL query string to validate
+ * @param options - Validation options
+ * @returns ValidationResult with isSafe=true if query passes,
+ *          or isSafe=false with a reason explaining why it was blocked
+ *
+ * @example
+ * ```typescript
+ * import { validate } from 'proxql';
+ *
+ * // Basic validation (blocks all non-SELECT)
+ * validate("SELECT * FROM users").isSafe  // true
+ * validate("DROP TABLE users").isSafe     // false
+ *
+ * // Allow writes
+ * validate("INSERT INTO logs VALUES (1)", { mode: "write_safe" }).isSafe  // true
+ *
+ * // Restrict to specific tables
+ * validate("SELECT * FROM users", {
+ *   allowedTables: ["products", "categories"]
+ * }).isSafe  // false
+ * ```
+ */
+declare function validate(sql: string, options?: ValidateOptions): ValidationResult;
+/**
+ * Check if a SQL query is safe (convenience wrapper).
+ *
+ * This is a shorthand for `validate(sql).isSafe`. Use this when you only
+ * need a boolean result and don't need the detailed ValidationResult.
+ *
+ * @param sql - The SQL query string to validate
+ * @param options - Validation options
+ * @returns true if the query passes all validation checks, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isSafe } from 'proxql';
+ *
+ * if (isSafe(userQuery)) {
+ *   executeQuery(userQuery);
+ * } else {
+ *   throw new Error("Query blocked");
+ * }
+ * ```
+ */
+declare function isSafe(sql: string, options?: ValidateOptions): boolean;
+declare const _default: {
+    validate: typeof validate;
+    isSafe: typeof isSafe;
+    Validator: typeof Validator;
+};
+
+export { type Mode, RuleSeverity, SecurityConfig, type SecurityConfigOptions, type ValidateOptions, ValidationResult, Validator, type ValidatorOptions, _default as default, isSafe, validate };