graphile-sql-expression-validator 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# graphile-sql-expression-validator
+
+A Graphile plugin for SQL expression validation and AST normalization. This plugin validates SQL expressions at the GraphQL layer before they reach the database, preventing SQL injection and ensuring only safe expressions are executed.
+
+## Installation
+
+```sh
+npm install graphile-sql-expression-validator
+```
+
+## Usage
+
+### Smart Comments
+
+Tag columns that contain SQL expressions with `@sqlExpression`:
+
+```sql
+COMMENT ON COLUMN collections_public.field.default_value IS E'@sqlExpression';
+```
+
+The plugin will automatically look for a companion `*_ast` column (e.g., `default_value_ast`) to store the parsed AST.
+
+#### Custom AST Field Name
+
+By default, the plugin looks for a companion column named `<column>_ast`. You can override this with `@rawSqlAstField`:
+
+```sql
+-- Use a custom AST column name
+COMMENT ON COLUMN collections_public.field.default_value IS E'@sqlExpression\n@rawSqlAstField my_custom_ast_column';
+```
+
+If `@rawSqlAstField` points to a non-existent column, the plugin will throw an error. If not specified, it falls back to the `<column>_ast` convention (and silently skips AST storage if that column doesn't exist).
+
+### Plugin Configuration
+
+```typescript
+import SqlExpressionValidatorPlugin from 'graphile-sql-expression-validator';
+
+const postgraphileOptions = {
+  appendPlugins: [SqlExpressionValidatorPlugin],
+  graphileBuildOptions: {
+    sqlExpressionValidator: {
+      // Optional: Additional allowed functions beyond defaults
+      allowedFunctions: ['my_custom_function'],
+      // Optional: Allowed schema names for schema-qualified functions
+      allowedSchemas: ['my_schema'],
+      // Optional: Maximum expression length (default: 10000)
+      maxExpressionLength: 5000,
+      // Optional: Auto-allow schemas owned by the current database
+      // Queries: SELECT schema_name FROM collections_public.schema 
+      //          WHERE database_id = jwt_private.current_database_id()
+      allowOwnedSchemas: true,
+      // Optional: Custom hook for dynamic schema resolution
+      getAdditionalAllowedSchemas: async (context) => {
+        // Return additional allowed schemas based on request context
+        return ['dynamic_schema'];
+      },
+    },
+  },
+};
+```
+
+## How It Works
+
+1. **On mutation input**, the plugin detects fields tagged with `@sqlExpression`
+2. **If text is provided**: Parses the SQL expression, validates the AST, and stores both the canonical text and AST
+3. **If AST is provided**: Validates the AST and deparses to canonical text
+4. **Validation includes**:
+   - Node type allowlist (constants, casts, operators, function calls)
+   - Function name allowlist for unqualified functions
+   - Schema allowlist for schema-qualified functions
+   - Rejection of dangerous constructs (subqueries, DDL, DML, column references)
+
+## Default Allowed Functions
+
+- `uuid_generate_v4`
+- `gen_random_uuid`
+- `now`
+- `current_timestamp`
+- `current_date`
+- `current_time`
+- `localtime`
+- `localtimestamp`
+- `clock_timestamp`
+- `statement_timestamp`
+- `transaction_timestamp`
+- `timeofday`
+- `random`
+- `setseed`
+
+## API
+
+### `parseAndValidateSqlExpression(expression, options)`
+
+Parse and validate a SQL expression string.
+
+```typescript
+import { parseAndValidateSqlExpression } from 'graphile-sql-expression-validator';
+
+const result = parseAndValidateSqlExpression('uuid_generate_v4()');
+// { valid: true, ast: {...}, canonicalText: 'uuid_generate_v4()' }
+
+const invalid = parseAndValidateSqlExpression('SELECT * FROM users');
+// { valid: false, error: 'Forbidden node type "SelectStmt"...' }
+```
+
+### `validateAst(ast, options)`
+
+Validate an existing AST and get canonical text.
+
+```typescript
+import { validateAst } from 'graphile-sql-expression-validator';
+
+const result = validateAst(myAst);
+// { valid: true, canonicalText: 'uuid_generate_v4()' }
+```
+
+## Security Notes
+
+- This plugin provides defense-in-depth at the GraphQL layer
+- It does not replace database-level security measures
+- Superuser/admin paths that bypass GraphQL are not protected
+- Always use RLS and proper database permissions as the primary security layer
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'graphile-build';
+export interface SqlExpressionValidatorOptions {
+    allowedFunctions?: string[];
+    allowedSchemas?: string[];
+    maxExpressionLength?: number;
+    allowOwnedSchemas?: boolean;
+    getAdditionalAllowedSchemas?: (context: any) => Promise<string[]>;
+}
+export declare function parseAndValidateSqlExpression(expression: string, options?: SqlExpressionValidatorOptions): Promise<{
+    valid: boolean;
+    ast?: any;
+    canonicalText?: string;
+    error?: string;
+}>;
+export declare function validateAst(ast: any, options?: SqlExpressionValidatorOptions): Promise<{
+    valid: boolean;
+    canonicalText?: string;
+    error?: string;
+}>;
+declare const SqlExpressionValidatorPlugin: Plugin;
+export default SqlExpressionValidatorPlugin;

package/esm/index.js

@@ -0,0 +1,341 @@
+import { parse } from 'pgsql-parser';
+import { deparse } from 'pgsql-deparser';
+const DEFAULT_ALLOWED_FUNCTIONS = [
+    'uuid_generate_v4',
+    'gen_random_uuid',
+    'now',
+    'current_timestamp',
+    'current_date',
+    'current_time',
+    'localtime',
+    'localtimestamp',
+    'clock_timestamp',
+    'statement_timestamp',
+    'transaction_timestamp',
+    'timeofday',
+    'random',
+    'setseed',
+];
+const ALLOWED_NODE_TYPES = new Set([
+    'A_Const',
+    'TypeCast',
+    'A_Expr',
+    'FuncCall',
+    'CoalesceExpr',
+    'NullTest',
+    'BoolExpr',
+    'CaseExpr',
+    'CaseWhen',
+]);
+const FORBIDDEN_NODE_TYPES = new Set([
+    'SelectStmt',
+    'InsertStmt',
+    'UpdateStmt',
+    'DeleteStmt',
+    'CreateStmt',
+    'AlterTableStmt',
+    'DropStmt',
+    'TruncateStmt',
+    'ColumnRef',
+    'SubLink',
+    'RangeVar',
+    'RangeSubselect',
+    'JoinExpr',
+    'FromExpr',
+]);
+function getNodeType(node) {
+    if (!node || typeof node !== 'object')
+        return null;
+    const keys = Object.keys(node);
+    if (keys.length === 1)
+        return keys[0];
+    return null;
+}
+function validateAstNode(node, allowedFunctions, allowedSchemas, path = []) {
+    if (!node || typeof node !== 'object') {
+        return { valid: true };
+    }
+    const nodeType = getNodeType(node);
+    if (nodeType && FORBIDDEN_NODE_TYPES.has(nodeType)) {
+        return {
+            valid: false,
+            error: `Forbidden node type "${nodeType}" at path: ${path.join('.')}`,
+        };
+    }
+    if (nodeType === 'FuncCall') {
+        const funcCall = node.FuncCall;
+        const funcName = funcCall?.funcname;
+        if (Array.isArray(funcName)) {
+            const names = funcName.map((n) => n.String?.sval || n.str || '');
+            const schemaName = names.length > 1 ? names[0] : null;
+            const functionName = names[names.length - 1];
+            if (schemaName) {
+                if (!allowedSchemas.includes(schemaName)) {
+                    return {
+                        valid: false,
+                        error: `Function schema "${schemaName}" is not in the allowed schemas list`,
+                    };
+                }
+            }
+            else {
+                if (!allowedFunctions.includes(functionName.toLowerCase())) {
+                    return {
+                        valid: false,
+                        error: `Function "${functionName}" is not in the allowed functions list`,
+                    };
+                }
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                const result = validateAstNode(value[i], allowedFunctions, allowedSchemas, [...path, key, String(i)]);
+                if (!result.valid)
+                    return result;
+            }
+        }
+        else if (value && typeof value === 'object') {
+            const result = validateAstNode(value, allowedFunctions, allowedSchemas, [
+                ...path,
+                key,
+            ]);
+            if (!result.valid)
+                return result;
+        }
+    }
+    return { valid: true };
+}
+export async function parseAndValidateSqlExpression(expression, options = {}) {
+    const { allowedFunctions = DEFAULT_ALLOWED_FUNCTIONS, allowedSchemas = [], maxExpressionLength = 10000, } = options;
+    if (!expression || typeof expression !== 'string') {
+        return { valid: false, error: 'Expression must be a non-empty string' };
+    }
+    if (expression.length > maxExpressionLength) {
+        return {
+            valid: false,
+            error: `Expression exceeds maximum length of ${maxExpressionLength} characters`,
+        };
+    }
+    if (expression.includes(';')) {
+        return {
+            valid: false,
+            error: 'Expression cannot contain semicolons (no stacked statements)',
+        };
+    }
+    try {
+        const wrappedSql = `SELECT (${expression})`;
+        const parseResult = await parse(wrappedSql);
+        if (!parseResult ||
+            !parseResult.stmts ||
+            parseResult.stmts.length !== 1) {
+            return { valid: false, error: 'Failed to parse expression' };
+        }
+        const stmt = parseResult.stmts[0]?.stmt;
+        if (!stmt?.SelectStmt) {
+            return { valid: false, error: 'Unexpected parse result structure' };
+        }
+        const targetList = stmt.SelectStmt.targetList;
+        if (!targetList || targetList.length !== 1) {
+            return { valid: false, error: 'Expected single expression' };
+        }
+        const resTarget = targetList[0]?.ResTarget;
+        if (!resTarget || !resTarget.val) {
+            return { valid: false, error: 'Could not extract expression from parse result' };
+        }
+        const expressionAst = resTarget.val;
+        const validationResult = validateAstNode(expressionAst, allowedFunctions.map((f) => f.toLowerCase()), allowedSchemas);
+        if (!validationResult.valid) {
+            return { valid: false, error: validationResult.error };
+        }
+        let canonicalText;
+        try {
+            canonicalText = await deparse([expressionAst]);
+        }
+        catch (deparseError) {
+            return {
+                valid: false,
+                error: `Failed to deparse expression: ${deparseError}`,
+            };
+        }
+        return {
+            valid: true,
+            ast: expressionAst,
+            canonicalText,
+        };
+    }
+    catch (parseError) {
+        return {
+            valid: false,
+            error: `Failed to parse SQL expression: ${parseError.message || parseError}`,
+        };
+    }
+}
+export async function validateAst(ast, options = {}) {
+    const { allowedFunctions = DEFAULT_ALLOWED_FUNCTIONS, allowedSchemas = [] } = options;
+    if (!ast || typeof ast !== 'object') {
+        return { valid: false, error: 'AST must be a non-null object' };
+    }
+    const validationResult = validateAstNode(ast, allowedFunctions.map((f) => f.toLowerCase()), allowedSchemas);
+    if (!validationResult.valid) {
+        return { valid: false, error: validationResult.error };
+    }
+    try {
+        const canonicalText = await deparse([ast]);
+        return { valid: true, canonicalText };
+    }
+    catch (deparseError) {
+        return {
+            valid: false,
+            error: `Failed to deparse AST: ${deparseError}`,
+        };
+    }
+}
+const OWNED_SCHEMAS_CACHE_KEY = Symbol('sqlExpressionValidator.ownedSchemas');
+async function resolveEffectiveOptions(baseOptions, gqlContext) {
+    const { allowedSchemas = [], allowOwnedSchemas = false, getAdditionalAllowedSchemas, ...rest } = baseOptions;
+    const effectiveSchemas = [...allowedSchemas];
+    if (allowOwnedSchemas && gqlContext?.pgClient) {
+        let ownedSchemas = gqlContext[OWNED_SCHEMAS_CACHE_KEY];
+        if (!ownedSchemas) {
+            try {
+                const result = await gqlContext.pgClient.query(`SELECT schema_name FROM collections_public.schema WHERE database_id = jwt_private.current_database_id()`);
+                ownedSchemas = result.rows.map((row) => row.schema_name);
+                gqlContext[OWNED_SCHEMAS_CACHE_KEY] = ownedSchemas;
+            }
+            catch (err) {
+                ownedSchemas = [];
+            }
+        }
+        effectiveSchemas.push(...ownedSchemas);
+    }
+    if (getAdditionalAllowedSchemas) {
+        try {
+            const additionalSchemas = await getAdditionalAllowedSchemas(gqlContext);
+            effectiveSchemas.push(...additionalSchemas);
+        }
+        catch (err) {
+        }
+    }
+    const uniqueSchemas = [...new Set(effectiveSchemas)];
+    return {
+        ...rest,
+        allowedSchemas: uniqueSchemas,
+    };
+}
+const SqlExpressionValidatorPlugin = (builder, options = {}) => {
+    const validatorOptions = options.sqlExpressionValidator || {};
+    builder.hook('GraphQLObjectType:fields:field', (field, build, context) => {
+        const { scope: { isRootMutation, fieldName, pgFieldIntrospection: table }, } = context;
+        if (!isRootMutation || !table) {
+            return field;
+        }
+        const sqlExpressionColumns = build.pgIntrospectionResultsByKind.attribute
+            .filter((attr) => attr.classId === table.id)
+            .filter((attr) => attr.tags?.sqlExpression);
+        if (sqlExpressionColumns.length === 0) {
+            return field;
+        }
+        const defaultResolver = (obj) => obj[fieldName];
+        const { resolve: oldResolve = defaultResolver, ...rest } = field;
+        return {
+            ...rest,
+            async resolve(source, args, gqlContext, info) {
+                const effectiveOptions = await resolveEffectiveOptions(validatorOptions, gqlContext);
+                for (const attr of sqlExpressionColumns) {
+                    const textGqlName = build.inflection.column(attr);
+                    const rawSqlAstFieldTag = attr.tags?.rawSqlAstField;
+                    const astDbName = typeof rawSqlAstFieldTag === 'string' && rawSqlAstFieldTag.trim()
+                        ? rawSqlAstFieldTag.trim()
+                        : `${attr.name}_ast`;
+                    const astAttr = build.pgIntrospectionResultsByKind.attribute.find((a) => a.classId === table.id && a.name === astDbName);
+                    let astGqlName = null;
+                    if (astAttr) {
+                        astGqlName = build.inflection.column(astAttr);
+                    }
+                    else if (typeof rawSqlAstFieldTag === 'string' && rawSqlAstFieldTag.trim()) {
+                        throw new Error(`@rawSqlAstField points to missing column "${astDbName}" on ${table.namespaceName}.${table.name}`);
+                    }
+                    const inputPath = findInputPath(args, textGqlName);
+                    const astInputPath = astGqlName ? findInputPath(args, astGqlName) : null;
+                    if (inputPath) {
+                        const textValue = getNestedValue(args, inputPath);
+                        if (textValue !== undefined && textValue !== null) {
+                            const result = await parseAndValidateSqlExpression(textValue, effectiveOptions);
+                            if (!result.valid) {
+                                throw new Error(`Invalid SQL expression in ${textGqlName}: ${result.error}`);
+                            }
+                            setNestedValue(args, inputPath, result.canonicalText);
+                            if (astGqlName && (astInputPath || canSetAstColumn(args, inputPath, astGqlName))) {
+                                const astPath = astInputPath || replaceLastSegment(inputPath, astGqlName);
+                                setNestedValue(args, astPath, result.ast);
+                            }
+                        }
+                    }
+                    if (astInputPath && !inputPath && astGqlName) {
+                        const astValue = getNestedValue(args, astInputPath);
+                        if (astValue !== undefined && astValue !== null) {
+                            const result = await validateAst(astValue, effectiveOptions);
+                            if (!result.valid) {
+                                throw new Error(`Invalid SQL expression AST in ${astGqlName}: ${result.error}`);
+                            }
+                            const textPath = replaceLastSegment(astInputPath, textGqlName);
+                            if (canSetColumn(args, astInputPath, textGqlName)) {
+                                setNestedValue(args, textPath, result.canonicalText);
+                            }
+                        }
+                    }
+                }
+                return oldResolve(source, args, gqlContext, info);
+            },
+        };
+    });
+};
+function findInputPath(obj, key, path = []) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === key) {
+            return [...path, k];
+        }
+        if (v && typeof v === 'object') {
+            const result = findInputPath(v, key, [...path, k]);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+}
+function getNestedValue(obj, path) {
+    let current = obj;
+    for (const key of path) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function setNestedValue(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        if (current[path[i]] === undefined) {
+            current[path[i]] = {};
+        }
+        current = current[path[i]];
+    }
+    current[path[path.length - 1]] = value;
+}
+function replaceLastSegment(path, newSegment) {
+    return [...path.slice(0, -1), newSegment];
+}
+function canSetAstColumn(args, textPath, astColumnName) {
+    const parentPath = textPath.slice(0, -1);
+    const parent = getNestedValue(args, parentPath);
+    return parent && typeof parent === 'object';
+}
+function canSetColumn(args, astPath, columnName) {
+    const parentPath = astPath.slice(0, -1);
+    const parent = getNestedValue(args, parentPath);
+    return parent && typeof parent === 'object';
+}
+export default SqlExpressionValidatorPlugin;

package/index.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'graphile-build';
+export interface SqlExpressionValidatorOptions {
+    allowedFunctions?: string[];
+    allowedSchemas?: string[];
+    maxExpressionLength?: number;
+    allowOwnedSchemas?: boolean;
+    getAdditionalAllowedSchemas?: (context: any) => Promise<string[]>;
+}
+export declare function parseAndValidateSqlExpression(expression: string, options?: SqlExpressionValidatorOptions): Promise<{
+    valid: boolean;
+    ast?: any;
+    canonicalText?: string;
+    error?: string;
+}>;
+export declare function validateAst(ast: any, options?: SqlExpressionValidatorOptions): Promise<{
+    valid: boolean;
+    canonicalText?: string;
+    error?: string;
+}>;
+declare const SqlExpressionValidatorPlugin: Plugin;
+export default SqlExpressionValidatorPlugin;

package/index.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAndValidateSqlExpression = parseAndValidateSqlExpression;
+exports.validateAst = validateAst;
+const pgsql_parser_1 = require("pgsql-parser");
+const pgsql_deparser_1 = require("pgsql-deparser");
+const DEFAULT_ALLOWED_FUNCTIONS = [
+    'uuid_generate_v4',
+    'gen_random_uuid',
+    'now',
+    'current_timestamp',
+    'current_date',
+    'current_time',
+    'localtime',
+    'localtimestamp',
+    'clock_timestamp',
+    'statement_timestamp',
+    'transaction_timestamp',
+    'timeofday',
+    'random',
+    'setseed',
+];
+const ALLOWED_NODE_TYPES = new Set([
+    'A_Const',
+    'TypeCast',
+    'A_Expr',
+    'FuncCall',
+    'CoalesceExpr',
+    'NullTest',
+    'BoolExpr',
+    'CaseExpr',
+    'CaseWhen',
+]);
+const FORBIDDEN_NODE_TYPES = new Set([
+    'SelectStmt',
+    'InsertStmt',
+    'UpdateStmt',
+    'DeleteStmt',
+    'CreateStmt',
+    'AlterTableStmt',
+    'DropStmt',
+    'TruncateStmt',
+    'ColumnRef',
+    'SubLink',
+    'RangeVar',
+    'RangeSubselect',
+    'JoinExpr',
+    'FromExpr',
+]);
+function getNodeType(node) {
+    if (!node || typeof node !== 'object')
+        return null;
+    const keys = Object.keys(node);
+    if (keys.length === 1)
+        return keys[0];
+    return null;
+}
+function validateAstNode(node, allowedFunctions, allowedSchemas, path = []) {
+    if (!node || typeof node !== 'object') {
+        return { valid: true };
+    }
+    const nodeType = getNodeType(node);
+    if (nodeType && FORBIDDEN_NODE_TYPES.has(nodeType)) {
+        return {
+            valid: false,
+            error: `Forbidden node type "${nodeType}" at path: ${path.join('.')}`,
+        };
+    }
+    if (nodeType === 'FuncCall') {
+        const funcCall = node.FuncCall;
+        const funcName = funcCall?.funcname;
+        if (Array.isArray(funcName)) {
+            const names = funcName.map((n) => n.String?.sval || n.str || '');
+            const schemaName = names.length > 1 ? names[0] : null;
+            const functionName = names[names.length - 1];
+            if (schemaName) {
+                if (!allowedSchemas.includes(schemaName)) {
+                    return {
+                        valid: false,
+                        error: `Function schema "${schemaName}" is not in the allowed schemas list`,
+                    };
+                }
+            }
+            else {
+                if (!allowedFunctions.includes(functionName.toLowerCase())) {
+                    return {
+                        valid: false,
+                        error: `Function "${functionName}" is not in the allowed functions list`,
+                    };
+                }
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                const result = validateAstNode(value[i], allowedFunctions, allowedSchemas, [...path, key, String(i)]);
+                if (!result.valid)
+                    return result;
+            }
+        }
+        else if (value && typeof value === 'object') {
+            const result = validateAstNode(value, allowedFunctions, allowedSchemas, [
+                ...path,
+                key,
+            ]);
+            if (!result.valid)
+                return result;
+        }
+    }
+    return { valid: true };
+}
+async function parseAndValidateSqlExpression(expression, options = {}) {
+    const { allowedFunctions = DEFAULT_ALLOWED_FUNCTIONS, allowedSchemas = [], maxExpressionLength = 10000, } = options;
+    if (!expression || typeof expression !== 'string') {
+        return { valid: false, error: 'Expression must be a non-empty string' };
+    }
+    if (expression.length > maxExpressionLength) {
+        return {
+            valid: false,
+            error: `Expression exceeds maximum length of ${maxExpressionLength} characters`,
+        };
+    }
+    if (expression.includes(';')) {
+        return {
+            valid: false,
+            error: 'Expression cannot contain semicolons (no stacked statements)',
+        };
+    }
+    try {
+        const wrappedSql = `SELECT (${expression})`;
+        const parseResult = await (0, pgsql_parser_1.parse)(wrappedSql);
+        if (!parseResult ||
+            !parseResult.stmts ||
+            parseResult.stmts.length !== 1) {
+            return { valid: false, error: 'Failed to parse expression' };
+        }
+        const stmt = parseResult.stmts[0]?.stmt;
+        if (!stmt?.SelectStmt) {
+            return { valid: false, error: 'Unexpected parse result structure' };
+        }
+        const targetList = stmt.SelectStmt.targetList;
+        if (!targetList || targetList.length !== 1) {
+            return { valid: false, error: 'Expected single expression' };
+        }
+        const resTarget = targetList[0]?.ResTarget;
+        if (!resTarget || !resTarget.val) {
+            return { valid: false, error: 'Could not extract expression from parse result' };
+        }
+        const expressionAst = resTarget.val;
+        const validationResult = validateAstNode(expressionAst, allowedFunctions.map((f) => f.toLowerCase()), allowedSchemas);
+        if (!validationResult.valid) {
+            return { valid: false, error: validationResult.error };
+        }
+        let canonicalText;
+        try {
+            canonicalText = await (0, pgsql_deparser_1.deparse)([expressionAst]);
+        }
+        catch (deparseError) {
+            return {
+                valid: false,
+                error: `Failed to deparse expression: ${deparseError}`,
+            };
+        }
+        return {
+            valid: true,
+            ast: expressionAst,
+            canonicalText,
+        };
+    }
+    catch (parseError) {
+        return {
+            valid: false,
+            error: `Failed to parse SQL expression: ${parseError.message || parseError}`,
+        };
+    }
+}
+async function validateAst(ast, options = {}) {
+    const { allowedFunctions = DEFAULT_ALLOWED_FUNCTIONS, allowedSchemas = [] } = options;
+    if (!ast || typeof ast !== 'object') {
+        return { valid: false, error: 'AST must be a non-null object' };
+    }
+    const validationResult = validateAstNode(ast, allowedFunctions.map((f) => f.toLowerCase()), allowedSchemas);
+    if (!validationResult.valid) {
+        return { valid: false, error: validationResult.error };
+    }
+    try {
+        const canonicalText = await (0, pgsql_deparser_1.deparse)([ast]);
+        return { valid: true, canonicalText };
+    }
+    catch (deparseError) {
+        return {
+            valid: false,
+            error: `Failed to deparse AST: ${deparseError}`,
+        };
+    }
+}
+const OWNED_SCHEMAS_CACHE_KEY = Symbol('sqlExpressionValidator.ownedSchemas');
+async function resolveEffectiveOptions(baseOptions, gqlContext) {
+    const { allowedSchemas = [], allowOwnedSchemas = false, getAdditionalAllowedSchemas, ...rest } = baseOptions;
+    const effectiveSchemas = [...allowedSchemas];
+    if (allowOwnedSchemas && gqlContext?.pgClient) {
+        let ownedSchemas = gqlContext[OWNED_SCHEMAS_CACHE_KEY];
+        if (!ownedSchemas) {
+            try {
+                const result = await gqlContext.pgClient.query(`SELECT schema_name FROM collections_public.schema WHERE database_id = jwt_private.current_database_id()`);
+                ownedSchemas = result.rows.map((row) => row.schema_name);
+                gqlContext[OWNED_SCHEMAS_CACHE_KEY] = ownedSchemas;
+            }
+            catch (err) {
+                ownedSchemas = [];
+            }
+        }
+        effectiveSchemas.push(...ownedSchemas);
+    }
+    if (getAdditionalAllowedSchemas) {
+        try {
+            const additionalSchemas = await getAdditionalAllowedSchemas(gqlContext);
+            effectiveSchemas.push(...additionalSchemas);
+        }
+        catch (err) {
+        }
+    }
+    const uniqueSchemas = [...new Set(effectiveSchemas)];
+    return {
+        ...rest,
+        allowedSchemas: uniqueSchemas,
+    };
+}
+const SqlExpressionValidatorPlugin = (builder, options = {}) => {
+    const validatorOptions = options.sqlExpressionValidator || {};
+    builder.hook('GraphQLObjectType:fields:field', (field, build, context) => {
+        const { scope: { isRootMutation, fieldName, pgFieldIntrospection: table }, } = context;
+        if (!isRootMutation || !table) {
+            return field;
+        }
+        const sqlExpressionColumns = build.pgIntrospectionResultsByKind.attribute
+            .filter((attr) => attr.classId === table.id)
+            .filter((attr) => attr.tags?.sqlExpression);
+        if (sqlExpressionColumns.length === 0) {
+            return field;
+        }
+        const defaultResolver = (obj) => obj[fieldName];
+        const { resolve: oldResolve = defaultResolver, ...rest } = field;
+        return {
+            ...rest,
+            async resolve(source, args, gqlContext, info) {
+                const effectiveOptions = await resolveEffectiveOptions(validatorOptions, gqlContext);
+                for (const attr of sqlExpressionColumns) {
+                    const textGqlName = build.inflection.column(attr);
+                    const rawSqlAstFieldTag = attr.tags?.rawSqlAstField;
+                    const astDbName = typeof rawSqlAstFieldTag === 'string' && rawSqlAstFieldTag.trim()
+                        ? rawSqlAstFieldTag.trim()
+                        : `${attr.name}_ast`;
+                    const astAttr = build.pgIntrospectionResultsByKind.attribute.find((a) => a.classId === table.id && a.name === astDbName);
+                    let astGqlName = null;
+                    if (astAttr) {
+                        astGqlName = build.inflection.column(astAttr);
+                    }
+                    else if (typeof rawSqlAstFieldTag === 'string' && rawSqlAstFieldTag.trim()) {
+                        throw new Error(`@rawSqlAstField points to missing column "${astDbName}" on ${table.namespaceName}.${table.name}`);
+                    }
+                    const inputPath = findInputPath(args, textGqlName);
+                    const astInputPath = astGqlName ? findInputPath(args, astGqlName) : null;
+                    if (inputPath) {
+                        const textValue = getNestedValue(args, inputPath);
+                        if (textValue !== undefined && textValue !== null) {
+                            const result = await parseAndValidateSqlExpression(textValue, effectiveOptions);
+                            if (!result.valid) {
+                                throw new Error(`Invalid SQL expression in ${textGqlName}: ${result.error}`);
+                            }
+                            setNestedValue(args, inputPath, result.canonicalText);
+                            if (astGqlName && (astInputPath || canSetAstColumn(args, inputPath, astGqlName))) {
+                                const astPath = astInputPath || replaceLastSegment(inputPath, astGqlName);
+                                setNestedValue(args, astPath, result.ast);
+                            }
+                        }
+                    }
+                    if (astInputPath && !inputPath && astGqlName) {
+                        const astValue = getNestedValue(args, astInputPath);
+                        if (astValue !== undefined && astValue !== null) {
+                            const result = await validateAst(astValue, effectiveOptions);
+                            if (!result.valid) {
+                                throw new Error(`Invalid SQL expression AST in ${astGqlName}: ${result.error}`);
+                            }
+                            const textPath = replaceLastSegment(astInputPath, textGqlName);
+                            if (canSetColumn(args, astInputPath, textGqlName)) {
+                                setNestedValue(args, textPath, result.canonicalText);
+                            }
+                        }
+                    }
+                }
+                return oldResolve(source, args, gqlContext, info);
+            },
+        };
+    });
+};
+function findInputPath(obj, key, path = []) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === key) {
+            return [...path, k];
+        }
+        if (v && typeof v === 'object') {
+            const result = findInputPath(v, key, [...path, k]);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+}
+function getNestedValue(obj, path) {
+    let current = obj;
+    for (const key of path) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function setNestedValue(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        if (current[path[i]] === undefined) {
+            current[path[i]] = {};
+        }
+        current = current[path[i]];
+    }
+    current[path[path.length - 1]] = value;
+}
+function replaceLastSegment(path, newSegment) {
+    return [...path.slice(0, -1), newSegment];
+}
+function canSetAstColumn(args, textPath, astColumnName) {
+    const parentPath = textPath.slice(0, -1);
+    const parent = getNestedValue(args, parentPath);
+    return parent && typeof parent === 'object';
+}
+function canSetColumn(args, astPath, columnName) {
+    const parentPath = astPath.slice(0, -1);
+    const parent = getNestedValue(args, parentPath);
+    return parent && typeof parent === 'object';
+}
+exports.default = SqlExpressionValidatorPlugin;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "graphile-sql-expression-validator",
+  "version": "0.2.0",
+  "description": "Graphile plugin for SQL expression validation and AST normalization",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "pnpm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "pgpm",
+    "plugin",
+    "postgres",
+    "graphql",
+    "sql",
+    "ast",
+    "validation",
+    "security"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "devDependencies": {
+    "makage": "^0.1.9",
+    "ts-jest": "^29.4.6"
+  },
+  "dependencies": {
+    "graphile-build": "^4.14.1",
+    "graphql": "15.10.1",
+    "pgsql-deparser": "^17.17.0",
+    "pgsql-parser": "^17.9.9"
+  },
+  "gitHead": "e53cd1f303d796268d94b47e95cde30916e39c1f"
+}