@memberjunction/global 5.51.2 → 5.51.4

package/dist/SQLScreeningScanner.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Dialect-aware SQL scanner for MemberJunction's SQL denylist screens.
+ *
+ * A denylist screen is only as good as its idea of which text is code. This scanner reads SQL the
+ * way SQL Server or PostgreSQL splits it into tokens and marks every string literal, quoted
+ * identifier and comment, so a screen checks exactly the text the database runs as code. When it
+ * cannot read the text the way the database would, it reports that, so the screen rejects the text
+ * instead of guessing.
+ *
+ * Used by `SQLExpressionValidator` and `DatabaseProviderBase.ValidateUserProvidedSQLClause`.
+ *
+ * @module @memberjunction/global/SQLScreeningScanner
+ */
+/** SQL dialects whose lexical rules {@link ScanSQLForScreening} knows. */
+export type SQLScreeningDialect = 'sqlserver' | 'postgresql';
+/**
+ * Every dialect {@link ScanSQLForScreening} knows. A screen that does not know which database will
+ * run the SQL must accept it under each one.
+ */
+export declare const SQL_SCREENING_DIALECTS: readonly SQLScreeningDialect[];
+/** Kinds of text that the database never runs as code. */
+export type SQLScreeningSpanKind = 'string' | 'identifier' | 'comment';
+/** One string literal, quoted identifier or comment found by {@link ScanSQLForScreening}. */
+export interface SQLScreeningSpan {
+    Kind: SQLScreeningSpanKind;
+    /** Offset of the first character, including a prefix such as `N` or `E`. */
+    Start: number;
+    /** Offset just past the last character. */
+    End: number;
+}
+/** Result of {@link ScanSQLForScreening}. */
+export interface SQLScreeningScan {
+    /** The dialect whose rules were applied. */
+    Dialect: SQLScreeningDialect;
+    /** True when every character was read the way the database reads it. When false, reject the text. */
+    Classified: boolean;
+    /** Why the text could not be classified; null when {@link Classified} is true. */
+    Error: string | null;
+    /** The string literals, quoted identifiers and comments found, in order. */
+    Spans: SQLScreeningSpan[];
+    /** Number of comments found. */
+    CommentCount: number;
+    /**
+     * The input with each string literal, quoted identifier and comment replaced by one space, and a
+     * space between a number and a word written against it. Only code remains, split where the
+     * database splits it, so `N'x'UNION` reads as ` UNION` and `1UNION` as `1 UNION`. Keyword,
+     * statement-separator and comment-marker checks read this. When {@link Classified} is false,
+     * the text from the point where the scan stopped is left as written.
+     */
+    Code: string;
+    /**
+     * {@link Code}, except each quoted identifier is written as its bare name between spaces, so
+     * `[sys].[objects]` reads as ` sys . objects `. Checks for object and function names read this,
+     * so quoting a name does not hide it.
+     */
+    CodeWithIdentifiers: string;
+    /**
+     * The first token that is not whitespace or a comment, when that token is an unquoted word and
+     * the character after it is ASCII, so every server ends the word in the same place. Null when a
+     * literal, quoted identifier, number or symbol comes first, or there is no token. Checks for the
+     * statement's opening keyword read this.
+     */
+    LeadingWord: string | null;
+}
+/**
+ * Reads `sql` the way `dialect` splits it into tokens. Returns the string literals, quoted
+ * identifiers and comments it contains, and the code that remains.
+ *
+ * Both dialects: `'…'` and `N'…'` strings, in which `''` is an escaped quote and a backslash is an
+ * ordinary character; `"…"` identifiers with `""` escapes; `--` comments to the end of the line; and
+ * nested block comments. SQL Server adds `[…]` identifiers with `]]` escapes. PostgreSQL adds `E'…'`
+ * strings, in which a backslash escapes the next character, and dollar-quoted strings (`$$…$$`,
+ * `$tag$…$tag$`); a `[` is code there.
+ *
+ * 🚨 Do not add backslash escapes to plain `'…'` strings. Neither server honors them (PostgreSQL is
+ * assumed to run with `standard_conforming_strings = on`, its default since 9.1), and a scanner that
+ * does reads `x = 'a\') ; DROP TABLE t; --'` as one literal while the database runs the DROP.
+ *
+ * The scan stops and reports an error, instead of guessing, when:
+ * - a string, quoted identifier, dollar-quoted string or block comment is not closed;
+ * - the text contains a NUL character;
+ * - a `--` comment contains a line break other than `\n` or `\r\n`;
+ * - a PostgreSQL `E'…'` string is followed by another quoted segment, which PostgreSQL can join to
+ *   it and read with backslash escapes;
+ * - on SQL Server, a number is followed by `e` and a word character (`1EXEC` splits two ways).
+ *
+ * @param sql The clause, expression or query to read
+ * @param dialect The dialect whose lexical rules apply
+ */
+export declare function ScanSQLForScreening(sql: string, dialect: SQLScreeningDialect): SQLScreeningScan;
+//# sourceMappingURL=SQLScreeningScanner.d.ts.map

package/dist/SQLScreeningScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SQLScreeningScanner.d.ts","sourceRoot":"","sources":["../src/SQLScreeningScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAAgC,CAAC;AAElG,0DAA0D;AAC1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAEvE,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC7B,4CAA4C;IAC5C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,qGAAqG;IACrG,UAAU,EAAE,OAAO,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AA2DD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAE/F"}

package/dist/SQLScreeningScanner.js

@@ -0,0 +1,332 @@
+/**
+ * @fileoverview Dialect-aware SQL scanner for MemberJunction's SQL denylist screens.
+ *
+ * A denylist screen is only as good as its idea of which text is code. This scanner reads SQL the
+ * way SQL Server or PostgreSQL splits it into tokens and marks every string literal, quoted
+ * identifier and comment, so a screen checks exactly the text the database runs as code. When it
+ * cannot read the text the way the database would, it reports that, so the screen rejects the text
+ * instead of guessing.
+ *
+ * Used by `SQLExpressionValidator` and `DatabaseProviderBase.ValidateUserProvidedSQLClause`.
+ *
+ * @module @memberjunction/global/SQLScreeningScanner
+ */
+/**
+ * Every dialect {@link ScanSQLForScreening} knows. A screen that does not know which database will
+ * run the SQL must accept it under each one.
+ */
+export const SQL_SCREENING_DIALECTS = ['sqlserver', 'postgresql'];
+const LEXICAL_RULES = {
+    sqlserver: {
+        BracketIdentifiers: true,
+        PostgresStrings: false,
+        // Letters and digits of any script. Other non-ASCII characters are not part of a word: SQL
+        // Server reads a currency symbol such as ¥ as the start of a money literal, so in `¥1SELECT`
+        // the keyword is a separate token.
+        WordStart: /[\p{L}_@#]/u,
+        WordPart: /[\p{L}\p{N}_@#$]/u,
+        BareExponent: true,
+    },
+    postgresql: {
+        BracketIdentifiers: false,
+        PostgresStrings: true,
+        WordStart: /[A-Za-z_\u0080-￿]/,
+        WordPart: /[A-Za-z0-9_$\u0080-￿]/,
+        BareExponent: false,
+    },
+};
+const DIGIT = /[0-9]/;
+const WHITESPACE = /\s/;
+/** Whitespace every server skips. Other Unicode spaces count as a token when finding the leading word. */
+const ASCII_WHITESPACE = /[ \t\n\r\f\v]/;
+const NON_ASCII = /[^\x00-\x7f]/;
+/**
+ * A numeric literal at `lastIndex` (sticky). An exponent needs digits, so in PostgreSQL's `1e'…'`
+ * the `e` is left to open an E'…' string.
+ */
+const NUMBER = /0[xX][0-9A-Fa-f]*|(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?/y;
+/** A PostgreSQL `$$` or `$tag$` delimiter at `lastIndex` (sticky). */
+const DOLLAR_DELIMITER = /\$(?:[A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$/y;
+/** Line breaks other than `\n` and `\r\n`. Servers disagree on whether they end a `--` comment. */
+const AMBIGUOUS_LINE_BREAKS = new Set(['\r', '\u000b', '\u000c', '\u0085', '
', '
']);
+/**
+ * Reads `sql` the way `dialect` splits it into tokens. Returns the string literals, quoted
+ * identifiers and comments it contains, and the code that remains.
+ *
+ * Both dialects: `'…'` and `N'…'` strings, in which `''` is an escaped quote and a backslash is an
+ * ordinary character; `"…"` identifiers with `""` escapes; `--` comments to the end of the line; and
+ * nested block comments. SQL Server adds `[…]` identifiers with `]]` escapes. PostgreSQL adds `E'…'`
+ * strings, in which a backslash escapes the next character, and dollar-quoted strings (`$$…$$`,
+ * `$tag$…$tag$`); a `[` is code there.
+ *
+ * 🚨 Do not add backslash escapes to plain `'…'` strings. Neither server honors them (PostgreSQL is
+ * assumed to run with `standard_conforming_strings = on`, its default since 9.1), and a scanner that
+ * does reads `x = 'a\') ; DROP TABLE t; --'` as one literal while the database runs the DROP.
+ *
+ * The scan stops and reports an error, instead of guessing, when:
+ * - a string, quoted identifier, dollar-quoted string or block comment is not closed;
+ * - the text contains a NUL character;
+ * - a `--` comment contains a line break other than `\n` or `\r\n`;
+ * - a PostgreSQL `E'…'` string is followed by another quoted segment, which PostgreSQL can join to
+ *   it and read with backslash escapes;
+ * - on SQL Server, a number is followed by `e` and a word character (`1EXEC` splits two ways).
+ *
+ * @param sql The clause, expression or query to read
+ * @param dialect The dialect whose lexical rules apply
+ */
+export function ScanSQLForScreening(sql, dialect) {
+    return new SQLScreeningScanner(sql, dialect).Scan();
+}
+/** One left-to-right pass over the input, with the dialect's rules. */
+class SQLScreeningScanner {
+    constructor(sql, dialect) {
+        this.sql = sql;
+        this.dialect = dialect;
+        this.spans = [];
+        this.code = [];
+        this.codeWithIdentifiers = [];
+        this.commentCount = 0;
+        this.pos = 0;
+        /** Offset of the first token that is not whitespace or a comment, once one is reached. */
+        this.leadingTokenStart = null;
+        this.leadingWord = null;
+        this.rules = LEXICAL_RULES[dialect];
+    }
+    Scan() {
+        if (!SQL_SCREENING_DIALECTS.includes(this.dialect))
+            return this.stop(`"${this.dialect}" is not a known SQL dialect`);
+        if (this.sql.includes('\0'))
+            return this.stop('the text contains a NUL character');
+        while (this.pos < this.sql.length) {
+            const error = this.readToken();
+            if (error !== null)
+                return this.stop(error);
+        }
+        return this.result(null);
+    }
+    /** Reads the token at `pos`. Returns why the text cannot be classified, or null. */
+    readToken() {
+        const c = this.sql[this.pos];
+        const next = this.sql[this.pos + 1] ?? '';
+        if (c === '-' && next === '-')
+            return this.readLineComment();
+        if (c === '/' && next === '*')
+            return this.readBlockComment();
+        if (this.leadingTokenStart === null && !ASCII_WHITESPACE.test(c))
+            this.leadingTokenStart = this.pos;
+        if (c === "'")
+            return this.readString(this.pos + 1);
+        if ((c === 'N' || c === 'n') && next === "'")
+            return this.readString(this.pos + 2);
+        if (this.rules.PostgresStrings && (c === 'E' || c === 'e') && next === "'")
+            return this.readEscapeString();
+        if (this.rules.PostgresStrings && c === '$') {
+            const delimiter = this.dollarDelimiterAt(this.pos);
+            if (delimiter !== null)
+                return this.readDollarString(delimiter);
+        }
+        if (c === '"')
+            return this.readQuotedIdentifier('"');
+        if (this.rules.BracketIdentifiers && c === '[')
+            return this.readQuotedIdentifier(']');
+        if (DIGIT.test(c) || (c === '.' && DIGIT.test(next)))
+            return this.readNumber();
+        if (this.rules.WordStart.test(c))
+            return this.readWord();
+        this.emitCode(this.pos + 1);
+        return null;
+    }
+    /** Reads a `'…'` string whose content starts at `contentStart`. */
+    readString(contentStart) {
+        const end = this.findQuoteEnd(contentStart, "'", false);
+        if (end === -1)
+            return 'a string literal is not closed';
+        this.emitSpan('string', end);
+        return null;
+    }
+    /** Reads a PostgreSQL `E'…'` string, in which a backslash escapes the next character. */
+    readEscapeString() {
+        const end = this.findQuoteEnd(this.pos + 2, "'", true);
+        if (end === -1)
+            return "an E'…' string is not closed";
+        if (this.quoteFollows(end)) {
+            return "an E'…' string is followed by another quoted segment, which PostgreSQL can read as part of it";
+        }
+        this.emitSpan('string', end);
+        return null;
+    }
+    /** Reads a PostgreSQL dollar-quoted string that opens with `delimiter`. */
+    readDollarString(delimiter) {
+        const close = this.sql.indexOf(delimiter, this.pos + delimiter.length);
+        if (close === -1)
+            return 'a dollar-quoted string is not closed';
+        this.emitSpan('string', close + delimiter.length);
+        return null;
+    }
+    /** Reads a `"…"` or `[…]` identifier; `close` is its closing character. */
+    readQuotedIdentifier(close) {
+        const end = this.findQuoteEnd(this.pos + 1, close, false);
+        if (end === -1)
+            return 'a quoted identifier is not closed';
+        const name = this.sql.slice(this.pos + 1, end - 1).split(close + close).join(close);
+        this.emitSpan('identifier', end, name);
+        return null;
+    }
+    /** Reads a `--` comment, which ends at the end of the line. */
+    readLineComment() {
+        let j = this.pos + 2;
+        while (j < this.sql.length && this.sql[j] !== '\n') {
+            if (this.sql[j] === '\r' && this.sql[j + 1] === '\n')
+                break;
+            if (AMBIGUOUS_LINE_BREAKS.has(this.sql[j])) {
+                return 'a -- comment contains a line break that database servers read differently';
+            }
+            j++;
+        }
+        this.commentCount++;
+        this.emitSpan('comment', j);
+        return null;
+    }
+    /** Reads a block comment. Block comments nest on both SQL Server and PostgreSQL. */
+    readBlockComment() {
+        let depth = 0;
+        let j = this.pos;
+        while (j < this.sql.length) {
+            if (this.sql[j] === '/' && this.sql[j + 1] === '*') {
+                depth++;
+                j += 2;
+            }
+            else if (this.sql[j] === '*' && this.sql[j + 1] === '/') {
+                depth--;
+                j += 2;
+                if (depth === 0) {
+                    this.commentCount++;
+                    this.emitSpan('comment', j);
+                    return null;
+                }
+            }
+            else {
+                j++;
+            }
+        }
+        return 'a block comment is not closed';
+    }
+    /** Reads a number. A word written against it is a separate token, so a space is added between. */
+    readNumber() {
+        NUMBER.lastIndex = this.pos;
+        const match = NUMBER.exec(this.sql);
+        const end = this.pos + (match ? match[0].length : 1);
+        const following = this.sql[end] ?? '';
+        const afterThat = this.sql[end + 1] ?? '';
+        if (this.rules.BareExponent && (following === 'e' || following === 'E') && this.rules.WordStart.test(afterThat)) {
+            return 'a number is followed by a word that starts with E, which the server can read as part of the number';
+        }
+        this.emitCode(end);
+        if (following !== '' && this.rules.WordStart.test(following))
+            this.emitBoundary();
+        return null;
+    }
+    /** Reads an unquoted keyword or identifier. */
+    readWord() {
+        let j = this.pos + 1;
+        while (j < this.sql.length && this.rules.WordPart.test(this.sql[j]))
+            j++;
+        if (this.pos === this.leadingTokenStart && !NON_ASCII.test(this.sql[j] ?? '')) {
+            this.leadingWord = this.sql.slice(this.pos, j);
+        }
+        this.emitCode(j);
+        return null;
+    }
+    /**
+     * Offset just past the `close` character that ends a quoted run whose content starts at `from`,
+     * or -1 when none does. A doubled `close` is an escaped one; with `backslashEscapes`, so is any
+     * character after a backslash.
+     */
+    findQuoteEnd(from, close, backslashEscapes) {
+        let j = from;
+        while (j < this.sql.length) {
+            const ch = this.sql[j];
+            if (backslashEscapes && ch === '\\') {
+                j += 2;
+            }
+            else if (ch !== close) {
+                j++;
+            }
+            else if (this.sql[j + 1] === close) {
+                j += 2;
+            }
+            else {
+                return j + 1;
+            }
+        }
+        return -1;
+    }
+    /** Whether only whitespace and `--` comments come between `from` and the next `'`. */
+    quoteFollows(from) {
+        let j = from;
+        while (j < this.sql.length) {
+            const ch = this.sql[j];
+            if (ch === "'")
+                return true;
+            if (ch === '-' && this.sql[j + 1] === '-') {
+                j = this.lineEnd(j);
+            }
+            else if (WHITESPACE.test(ch)) {
+                j++;
+            }
+            else {
+                return false;
+            }
+        }
+        return false;
+    }
+    /** Offset of the first `\n` or `\r` at or after `from`, or the input length. */
+    lineEnd(from) {
+        let j = from;
+        while (j < this.sql.length && this.sql[j] !== '\n' && this.sql[j] !== '\r')
+            j++;
+        return j;
+    }
+    /** The `$$` or `$tag$` delimiter at `at`, or null when the `$` does not open a dollar-quoted string. */
+    dollarDelimiterAt(at) {
+        DOLLAR_DELIMITER.lastIndex = at;
+        return DOLLAR_DELIMITER.exec(this.sql)?.[0] ?? null;
+    }
+    /** Copies code up to `end` into both projections. */
+    emitCode(end) {
+        const text = this.sql.slice(this.pos, end);
+        this.code.push(text);
+        this.codeWithIdentifiers.push(text);
+        this.pos = end;
+    }
+    /** Records a span up to `end` and writes a space for it, or an identifier's bare name. */
+    emitSpan(kind, end, identifierName) {
+        this.spans.push({ Kind: kind, Start: this.pos, End: end });
+        this.code.push(' ');
+        this.codeWithIdentifiers.push(identifierName === undefined ? ' ' : ` ${identifierName} `);
+        this.pos = end;
+    }
+    /** Writes a token boundary that the input leaves implicit. */
+    emitBoundary() {
+        this.code.push(' ');
+        this.codeWithIdentifiers.push(' ');
+    }
+    /** Ends the scan at `pos`, leaving the unread text as written. */
+    stop(error) {
+        this.emitCode(this.sql.length);
+        return this.result(error);
+    }
+    result(error) {
+        return {
+            Dialect: this.dialect,
+            Classified: error === null,
+            Error: error,
+            Spans: this.spans,
+            CommentCount: this.commentCount,
+            Code: this.code.join(''),
+            CodeWithIdentifiers: this.codeWithIdentifiers.join(''),
+            LeadingWord: this.leadingWord,
+        };
+    }
+}
+//# sourceMappingURL=SQLScreeningScanner.js.map

package/dist/SQLScreeningScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SQLScreeningScanner.js","sourceRoot":"","sources":["../src/SQLScreeningScanner.ts"],"names":[],"mappings":"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"}

package/dist/SafeExpressionEvaluator.d.ts

@@ -9,6 +9,33 @@
  * @author MemberJunction.com
  * @since 2.76.0
  */
+/**
+ * Namespace globals whose listed methods a condition may CALL, keyed by namespace name.
+ *
+ * Both halves of `Math.abs(x)` are fixed identifiers in the AST, so admitting them adds no dynamic
+ * lookup: the four invariants that close the sandbox escape — literal-only computed keys, no
+ * `constructor`/`__proto__`/`prototype`, a closed non-computed call surface with no
+ * `call`/`apply`/`bind`, and screened free identifiers — are all untouched by this list.
+ *
+ * Every entry is a pure value function. `Math.random` is deliberately absent (a condition that
+ * evaluates differently on each run is not a guard), as are `Object.assign`,
+ * `Object.defineProperty` and `Object.setPrototypeOf`, which mutate.
+ */
+export declare const SAFE_GLOBAL_NAMESPACE_METHODS: ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * Global functions a condition may call by bare name — the coercions and numeric predicates that
+ * authored specs use (`Number(payload.count) > 3`, `isNaN(payload.count)`).
+ */
+export declare const SAFE_GLOBAL_CALLABLES: ReadonlySet<string>;
+/**
+ * Every global name a condition may reference, as a namespace or as a bare callable.
+ *
+ * **This is the single source of truth for the ambient globals of the condition dialect.** It lives
+ * beside the policy screen that enforces it so a caller validating conditions ahead of evaluation
+ * (`ai-core-plus`'s task-graph door) cannot bless a name the runtime would refuse — the failure mode
+ * that shipped once already, where the door's own list and the evaluator disagreed silently.
+ */
+export declare const SAFE_EXPRESSION_GLOBALS: ReadonlySet<string>;
 /**
  * Result of expression evaluation including success status and diagnostics
  */
@@ -29,11 +56,22 @@ export interface ExpressionEvaluationResult {
  * Supported operations:
  * - Comparison: ==, ===, !=, !==, <, >, <=, >=
  * - Logical: &&, ||, !
- * - Property access: dot notation (e.g., payload.customer.name)
- * - Array access: bracket notation (e.g., items[0])
+ * - Property access: dot notation (e.g., payload.customer.name), including optional chaining (`?.`)
+ * - Array access: bracket notation with a literal index/key (e.g., items[0])
  * - Safe methods: .length, .includes(), .startsWith(), .endsWith()
  * - Array methods: .some(), .every(), .find(), .filter()
- * - Type checking: typeof, instanceof (limited to safe types)
+ * - Safe globals: the namespaces and bare callables in {@link SAFE_EXPRESSION_GLOBALS}
+ *   (e.g. `Math.abs(output.delta) < 5`, `Number(payload.count) > 3`, `Object.keys(payload).length`)
+ * - Type checking: typeof
+ *
+ * Safety is enforced by parsing the expression to an AST and walking it against
+ * an ALLOWLIST of node types before it is compiled — an unlisted construct
+ * (computed member access with a non-literal key, `.constructor`/`__proto__`
+ * access, any call outside the safe-method and safe-global lists, host-global
+ * identifiers, etc.) is rejected at validation time and never reaches the compiler. A structural
+ * allowlist cannot be defeated by string concatenation the way a textual
+ * denylist can, and it does not over-reject data that merely mentions a reserved
+ * word (e.g. `name == 'constructor'` is a legal comparison).
  *
  * @class SafeExpressionEvaluator
  *
@@ -62,10 +100,24 @@ export interface ExpressionEvaluationResult {
  */
 export declare class SafeExpressionEvaluator {
     /**
-     * Patterns that indicate potentially dangerous code
+     * Identifiers that must never resolve to a host global. Because the compiled
+     * function runs in global scope, a bare `process`/`Function`/`globalThis`/…
+     * would reach the real global object; identifiers are atomic AST tokens, so a
+     * name that is split with string concatenation parses as separate identifiers
+     * or an operator and is caught by the structural rules instead.
      * @private
      */
-    private static readonly DANGEROUS_PATTERNS;
+    private static readonly DANGEROUS_IDENTIFIERS;
+    /**
+     * Property names that open the prototype chain / constructor climb. Denied on
+     * both dotted (`x.constructor`) and literal-bracket (`x["constructor"]`) access.
+     * @private
+     */
+    private static readonly DANGEROUS_PROPERTY_NAMES;
+    /** Binary operators the evaluator permits. `instanceof`/`in`/bitwise are excluded. @private */
+    private static readonly ALLOWED_BINARY_OPERATORS;
+    /** Unary operators the evaluator permits. `delete`/`void` are excluded. @private */
+    private static readonly ALLOWED_UNARY_OPERATORS;
     /**
      * Cache for compiled expressions to improve performance on repeated evaluations
      * @private
@@ -87,7 +139,8 @@ export declare class SafeExpressionEvaluator {
      */
     evaluate(expression: string, context: Record<string, any>, enableDiagnostics?: boolean): ExpressionEvaluationResult;
     /**
-     * Validates an expression for safety
+     * Validates an expression for safety by parsing it and walking the AST against
+     * an allowlist. Returns an error message if any construct is not permitted.
      *
      * @param {string} expression - The expression to validate
      *
@@ -96,6 +149,44 @@ export declare class SafeExpressionEvaluator {
      * @private
      */
     private validateExpression;
+    /** Builds the standard rejection message. @private */
+    private forbidden;
+    /**
+     * Walks an AST node against the allowlist. Returns an error message on the first
+     * disallowed construct, or null if the entire subtree is permitted.
+     * @private
+     */
+    private checkNode;
+    /**
+     * Member access is allowed for dotted property reads and literal-key bracket
+     * reads, but never for a computed key built at runtime (the string-concat
+     * escape route) or a prototype-chain property.
+     * @private
+     */
+    private checkMemberExpression;
+    /**
+     * A call is admitted only when its callee is a FIXED name on one of two allowlists: a bare
+     * safe global (`parseInt(...)`) or a dotted method that is either a safe instance method or a
+     * method of a safe global namespace (`Math.abs(...)`). Everything else — a computed callee, an
+     * unlisted bare identifier (`eval(...)`, `Function(...)`), a call on a call's result that is
+     * not itself a safe method — is rejected.
+     * @private
+     */
+    private checkCallExpression;
+    /**
+     * Whether `<receiver>.<method>()` names a permitted call: a safe instance method on any value,
+     * or a method of a safe global namespace when the receiver is that namespace by bare name.
+     * @private
+     */
+    private isCallableMethod;
+    /** Walks a call's arguments; spreads are rejected outright. @private */
+    private checkCallArguments;
+    /**
+     * Arrow functions are permitted only as callback arguments to the safe array
+     * methods; parameters must be simple identifiers and the body an expression.
+     * @private
+     */
+    private checkArrowFunction;
     /**
      * Creates a safe context object with only allowed properties
      *
@@ -126,6 +217,40 @@ export declare class SafeExpressionEvaluator {
      * @private
      */
     private cloneValue;
+    /**
+     * Checks whether an expression *could* be evaluated, without evaluating it.
+     *
+     * The difference matters because `evaluate` reports two unrelated problems the same way. Given
+     * a condition authored against a runtime envelope, an empty context makes `payload.x > 1` fail
+     * with `payload is not defined` — indistinguishable, by result shape, from `payload.x >` failing
+     * with `Unexpected token`. One is a typo the author should be told about at the door; the other
+     * is a perfectly good condition that simply has no data yet. A submit-time check built on
+     * `evaluate` therefore refuses every legitimate condition.
+     *
+     * So this compiles and never runs. The expression goes through the same policy screen
+     * `evaluate` applies (the AST allowlist), then the same function body is BUILT and discarded —
+     * never invoked. Values are never consulted, which is precisely the property wanted: unknown
+     * identifiers, absent properties and undefined chains all PASS, because none of them is a syntax
+     * error and whether they resolve is a question about a run that has not happened yet.
+     *
+     * **Compilation is not evaluation**, and the distinction is load-bearing for safety: `Function`
+     * parses the body and returns; nothing in the expression executes. The policy screen still runs
+     * first, so the constructs `evaluate` refuses are refused here too — those produce a permanent
+     * runtime refusal, and an author is better told now.
+     *
+     * `Undecidable` is the honest third answer. A host that forbids dynamic compilation (a strict
+     * CSP without `unsafe-eval`) cannot answer the question at all, and a validator that read that
+     * as "invalid" would refuse every condition in the browser. Callers should treat it as a pass.
+     *
+     * @param expression the expression to check
+     * @returns `Valid: true` when it parses; `Valid: false` with `Error` when it definitely does
+     *          not; `Valid: true` with `Undecidable: true` when this environment cannot compile
+     */
+    validateSyntax(expression: string): {
+        Valid: boolean;
+        Error?: string;
+        Undecidable?: boolean;
+    };
     /**
      * Evaluates multiple expressions and returns all results
      *

package/dist/SafeExpressionEvaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SafeExpressionEvaluator.d.ts","sourceRoot":"","sources":["../src/SafeExpressionEvaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC7B,cAAc,EAAE,MAAM,CAAC;KAC1B,CAAC;CACL;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,uBAAuB;IAChC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CA4BxC;IAEF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAuD;IAEhG;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAoBlC;IAEF;;;;;;;;OAQG;IACI,QAAQ,CACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,iBAAiB,GAAE,OAAe,GACnC,0BAA0B;IAwE7B;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAwDlB;;;;;;;OAOG;IACI,gBAAgB,CACnB,WAAW,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,EACvD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC;CAUhD;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,yBAAgC,CAAC"}
+{"version":3,"file":"SafeExpressionEvaluator.d.ts","sourceRoot":"","sources":["../src/SafeExpressionEvaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuBH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAUjF,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAEpD,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAGtD,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC7B,cAAc,EAAE,MAAM,CAAC;KAC1B,CAAC;CACL;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,uBAAuB;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAK1C;IAEH;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAE7C;IAEH,+FAA+F;IAC/F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAE7C;IAEH,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAA8C;IAE7F;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAuD;IAEhG;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAoBlC;IAEF;;;;;;;;OAQG;IACI,QAAQ,CACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,iBAAiB,GAAE,OAAe,GACnC,0BAA0B;IAwE7B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IA4C1B,sDAAsD;IACtD,OAAO,CAAC,SAAS;IAIjB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAmEjB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IA2B3B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAUxB,wEAAwE;IACxE,OAAO,CAAC,kBAAkB;IAW1B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAwDlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACI,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE;IAqBpG;;;;;;;OAOG;IACI,gBAAgB,CACnB,WAAW,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,EACvD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC;CAUhD;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,yBAAgC,CAAC"}