@sentriflow/core 0.1.0

package/src/json-rules/ExpressionEvaluator.ts

@@ -0,0 +1,292 @@
+// packages/core/src/json-rules/ExpressionEvaluator.ts
+
+/**
+ * Sandboxed Expression Evaluator for JSON Rules
+ *
+ * Evaluates simple JavaScript expressions in a secure sandbox.
+ * Provides access to helper functions while blocking dangerous operations.
+ */
+
+import { createContext, Script, type Context as VMContext } from 'vm';
+import type { ConfigNode } from '../types/ConfigNode';
+import { type HelperRegistry, getHelperRegistry, VENDOR_NAMESPACES } from './HelperRegistry';
+
+/** Maximum expression length to prevent DoS */
+const MAX_EXPR_LENGTH = 1000;
+
+/** Timeout for expression evaluation in milliseconds */
+const EXPR_TIMEOUT_MS = 50;
+
+/** Patterns that are blocked for security */
+const BLOCKED_PATTERNS = [
+    'require',
+    'import',
+    'eval',
+    'Function',
+    'process',
+    'global',
+    'globalThis',
+    'window',
+    '__proto__',
+    'constructor',
+    'prototype',
+    'Reflect',
+    'Proxy',
+    'module',
+    'exports',
+    'Buffer',
+    'setTimeout',
+    'setInterval',
+    'setImmediate',
+    'clearTimeout',
+    'clearInterval',
+    'clearImmediate',
+    'fetch',
+    'XMLHttpRequest',
+    'WebSocket',
+    // Additional security patterns
+    'arguments',  // Special object in functions
+    'this',       // Context access
+    'with',       // Scope manipulation
+];
+
+/**
+ * Pre-compiled script cache for performance.
+ */
+const scriptCache = new Map<string, Script>();
+
+/**
+ * Freeze an object deeply to prevent modification.
+ */
+function deepFreeze<T>(obj: T): T {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+
+    Object.freeze(obj);
+
+    for (const key of Object.keys(obj)) {
+        const value = (obj as Record<string, unknown>)[key];
+        if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+
+    return obj;
+}
+
+/**
+ * Create a frozen, safe copy of a ConfigNode for sandbox use.
+ * Only exposes safe properties, no methods or circular references.
+ */
+function createSafeNode(node: ConfigNode): Readonly<{
+    id: string;
+    type: string;
+    rawText: string;
+    params: readonly string[];
+    children: readonly ReturnType<typeof createSafeNode>[];
+}> {
+    return deepFreeze({
+        id: node.id,
+        type: node.type,
+        rawText: node.rawText,
+        params: [...node.params],
+        children: node.children.map(createSafeNode),
+    });
+}
+
+/**
+ * Validate an expression for security.
+ * Returns true if the expression is safe to evaluate.
+ */
+export function isValidExpression(expr: string): boolean {
+    // Check length
+    if (expr.length > MAX_EXPR_LENGTH) {
+        return false;
+    }
+
+    // Check for blocked patterns
+    const exprLower = expr.toLowerCase();
+    for (const pattern of BLOCKED_PATTERNS) {
+        if (exprLower.includes(pattern.toLowerCase())) {
+            return false;
+        }
+    }
+
+    // Block template literals with expressions
+    if (expr.includes('${')) {
+        return false;
+    }
+
+    // Block assignment operators
+    if (/[^=!<>]=[^=]/.test(expr)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Expression Evaluator class for sandboxed expression evaluation.
+ * Provides pre-compilation and caching for performance.
+ */
+export class ExpressionEvaluator {
+    private readonly sandbox: VMContext;
+    private readonly registry: HelperRegistry;
+
+    constructor(registry?: HelperRegistry) {
+        this.registry = registry ?? getHelperRegistry();
+        this.sandbox = this.createSandbox();
+    }
+
+    /**
+     * Create a sandboxed VM context with helpers available.
+     */
+    private createSandbox(): VMContext {
+        // Start with safe primitives
+        const sandboxObj: Record<string, unknown> = {
+            // Safe primitives
+            true: true,
+            false: false,
+            undefined: undefined,
+            null: null,
+            NaN: NaN,
+            Infinity: Infinity,
+
+            // Safe built-in constructors (frozen)
+            Boolean: Object.freeze(Boolean),
+            Number: Object.freeze(Number),
+            String: Object.freeze(String),
+            Array: Object.freeze(Array),
+            Object: Object.freeze(Object),
+            RegExp: Object.freeze(RegExp),
+            JSON: Object.freeze(JSON),
+            Math: Object.freeze(Math),
+
+            // Node placeholder (set per evaluation)
+            node: null,
+        };
+
+        // Add common helpers at top level
+        for (const [key, value] of Object.entries(this.registry)) {
+            if (typeof value === 'function') {
+                sandboxObj[key] = value;
+            }
+        }
+
+        // Add vendor namespaces
+        for (const namespace of VENDOR_NAMESPACES) {
+            const vendorHelpers = this.registry[namespace];
+            if (vendorHelpers && typeof vendorHelpers === 'object') {
+                sandboxObj[namespace] = Object.freeze({ ...vendorHelpers });
+            }
+        }
+
+        return createContext(Object.freeze(sandboxObj));
+    }
+
+    /**
+     * Pre-compile an expression for later evaluation.
+     * Call this at rule load time for performance.
+     *
+     * @param expr The expression to compile
+     * @returns true if compilation succeeded
+     */
+    precompile(expr: string): boolean {
+        if (!isValidExpression(expr)) {
+            return false;
+        }
+
+        if (scriptCache.has(expr)) {
+            return true;
+        }
+
+        try {
+            const script = new Script(`(${expr})`, {
+                filename: 'expr.js',
+            });
+            scriptCache.set(expr, script);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Evaluate an expression against a node.
+     *
+     * @param expr The expression to evaluate
+     * @param node The ConfigNode to evaluate against
+     * @returns The evaluation result as a boolean
+     */
+    evaluate(expr: string, node: ConfigNode): boolean {
+        // Validate expression
+        if (!isValidExpression(expr)) {
+            return false;
+        }
+
+        // Get or compile script
+        let script = scriptCache.get(expr);
+        if (!script) {
+            try {
+                script = new Script(`(${expr})`, {
+                    filename: 'expr.js',
+                });
+                scriptCache.set(expr, script);
+            } catch {
+                return false; // Compilation error
+            }
+        }
+
+        // Set node in sandbox (create a new context each time for isolation)
+        const evalContext = createContext({
+            ...this.sandbox,
+            node: createSafeNode(node),
+        });
+
+        try {
+            const result = script.runInContext(evalContext, {
+                timeout: EXPR_TIMEOUT_MS,
+            });
+            return Boolean(result);
+        } catch {
+            return false; // Runtime error or timeout
+        }
+    }
+
+    /**
+     * Clear the script cache (useful for testing).
+     */
+    static clearCache(): void {
+        scriptCache.clear();
+    }
+}
+
+/**
+ * Create a new ExpressionEvaluator instance.
+ * The evaluator can be reused across multiple rule evaluations.
+ */
+export function createExpressionEvaluator(registry?: HelperRegistry): ExpressionEvaluator {
+    return new ExpressionEvaluator(registry);
+}
+
+// Default singleton evaluator for convenience
+let defaultEvaluator: ExpressionEvaluator | null = null;
+
+/**
+ * Get the default expression evaluator (singleton).
+ */
+export function getExpressionEvaluator(): ExpressionEvaluator {
+    if (!defaultEvaluator) {
+        defaultEvaluator = new ExpressionEvaluator();
+    }
+    return defaultEvaluator;
+}
+
+/**
+ * Clear the default evaluator (useful for testing).
+ */
+export function clearExpressionEvaluator(): void {
+    defaultEvaluator = null;
+    ExpressionEvaluator.clearCache();
+}

package/src/json-rules/HelperRegistry.ts

@@ -0,0 +1,177 @@
+// packages/core/src/json-rules/HelperRegistry.ts
+
+/**
+ * Helper Registry for JSON Rules
+ *
+ * Provides a registry of all helper functions available to JSON rules.
+ * Helpers are organized by namespace (vendor) for clarity.
+ * Vendor namespaces are derived dynamically from the helpers module.
+ */
+
+import * as helpers from '../helpers';
+import { VENDOR_NAMESPACES as HELPER_VENDOR_NAMESPACES, getAllVendorModules } from '../helpers';
+
+/**
+ * Type representing any helper function.
+ */
+export type HelperFunction = (...args: unknown[]) => unknown;
+
+/**
+ * Vendor namespace containing helper functions.
+ */
+export type VendorHelpers = Record<string, HelperFunction>;
+
+/**
+ * Vendor namespaces for helper organization.
+ * Dynamically derived from the helpers module - single source of truth.
+ */
+export const VENDOR_NAMESPACES = HELPER_VENDOR_NAMESPACES;
+
+export type VendorNamespace = (typeof VENDOR_NAMESPACES)[number];
+
+/**
+ * Complete helper registry with common helpers and vendor namespaces.
+ * Vendor properties are dynamically typed based on VendorNamespace.
+ */
+export type HelperRegistry = {
+    // Common helpers (no namespace required)
+    [key: string]: HelperFunction | VendorHelpers;
+} & {
+    // Vendor namespaces - dynamically typed from VendorNamespace
+    [K in VendorNamespace]: VendorHelpers;
+};
+
+/**
+ * Extract only function exports from a module object.
+ */
+function extractFunctions(module: Record<string, unknown>): VendorHelpers {
+    const result: VendorHelpers = {};
+    for (const [key, value] of Object.entries(module)) {
+        if (typeof value === 'function') {
+            result[key] = value as HelperFunction;
+        }
+    }
+    return result;
+}
+
+/**
+ * Create a helper registry with all available helpers.
+ * Common helpers are available at the top level.
+ * Vendor-specific helpers are namespaced (e.g., "cisco.isTrunkPort").
+ */
+export function createHelperRegistry(): HelperRegistry {
+    // Extract common helpers (these are re-exported at the top level)
+    const commonHelpers = extractFunctions(helpers as unknown as Record<string, unknown>);
+
+    // Get all vendor modules dynamically
+    const vendorModules = getAllVendorModules();
+
+    // Build registry with common helpers and vendor namespaces
+    const registry = { ...commonHelpers } as HelperRegistry;
+
+    // Add each vendor namespace dynamically
+    for (const namespace of VENDOR_NAMESPACES) {
+        const vendorModule = vendorModules[namespace];
+        if (vendorModule) {
+            registry[namespace] = extractFunctions(vendorModule as unknown as Record<string, unknown>);
+        }
+    }
+
+    return registry;
+}
+
+/**
+ * Resolve a helper function by name.
+ * Supports both flat names (e.g., "hasChildCommand") and
+ * namespaced names (e.g., "cisco.isTrunkPort").
+ *
+ * @param registry The helper registry
+ * @param helperName The helper name to resolve
+ * @returns The helper function, or undefined if not found
+ */
+export function resolveHelper(
+    registry: HelperRegistry,
+    helperName: string
+): HelperFunction | undefined {
+    // Check for namespaced helper (e.g., "cisco.isTrunkPort")
+    if (helperName.includes('.')) {
+        const [namespace, name] = helperName.split('.', 2);
+        if (!namespace || !name) return undefined;
+
+        const vendorHelpers = registry[namespace];
+        if (vendorHelpers && typeof vendorHelpers === 'object') {
+            const helper = vendorHelpers[name];
+            return typeof helper === 'function' ? helper : undefined;
+        }
+        return undefined;
+    }
+
+    // Try common helpers at top level
+    const helper = registry[helperName];
+    if (typeof helper === 'function') {
+        return helper;
+    }
+
+    return undefined;
+}
+
+/**
+ * Get a list of all available helper names.
+ * Useful for validation and documentation.
+ *
+ * @param registry The helper registry
+ * @returns Array of helper names (both flat and namespaced)
+ */
+export function getAvailableHelpers(registry: HelperRegistry): string[] {
+    const helpers: string[] = [];
+
+    // Add common helpers
+    for (const [key, value] of Object.entries(registry)) {
+        if (typeof value === 'function') {
+            helpers.push(key);
+        }
+    }
+
+    // Add namespaced helpers
+    for (const namespace of VENDOR_NAMESPACES) {
+        const vendorHelpers = registry[namespace];
+        if (vendorHelpers && typeof vendorHelpers === 'object') {
+            for (const key of Object.keys(vendorHelpers)) {
+                helpers.push(`${namespace}.${key}`);
+            }
+        }
+    }
+
+    return helpers.sort();
+}
+
+/**
+ * Check if a helper name exists in the registry.
+ *
+ * @param registry The helper registry
+ * @param helperName The helper name to check
+ * @returns true if the helper exists
+ */
+export function hasHelper(registry: HelperRegistry, helperName: string): boolean {
+    return resolveHelper(registry, helperName) !== undefined;
+}
+
+// Singleton registry instance for performance
+let cachedRegistry: HelperRegistry | null = null;
+
+/**
+ * Get the global helper registry (cached for performance).
+ */
+export function getHelperRegistry(): HelperRegistry {
+    if (!cachedRegistry) {
+        cachedRegistry = createHelperRegistry();
+    }
+    return cachedRegistry;
+}
+
+/**
+ * Clear the cached registry (useful for testing).
+ */
+export function clearHelperRegistryCache(): void {
+    cachedRegistry = null;
+}