coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/formula_engine/__init__.py

@@ -0,0 +1,81 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Formula engine package.
+
+This package contains the refactored formula engine with modular architecture:
+- AST parsing and evaluation using Visitor pattern
+- Step execution using Strategy pattern
+- Validation, tables, execution, and results modules
+"""
+
+from __future__ import annotations
+
+# Import from formula_engine_examples
+# EXAMPLE_PROGRESSIVE_TAX_SCHEMA is the new generic name
+# EXAMPLE_IR_NICARAGUA_SCHEMA is kept for backward compatibility (deprecated)
+from coati_payroll.formula_engine_examples import (
+    EXAMPLE_PROGRESSIVE_TAX_SCHEMA,
+    EXAMPLE_IR_NICARAGUA_SCHEMA,
+)
+
+# Import main engine and functions
+from .engine import FormulaEngine, calculate_with_rule, get_available_sources_for_ui
+
+# Import exceptions
+from .exceptions import CalculationError, FormulaEngineError, TaxEngineError, ValidationError
+
+# Import utilities for backward compatibility
+from .ast.type_converter import safe_divide, to_decimal
+
+# Import submodules
+from .ast import (
+    ALLOWED_AST_TYPES,
+    ASTVisitor,
+    COMPARISON_OPERATORS,
+    ExpressionEvaluator,
+    SAFE_FUNCTIONS,
+    SAFE_OPERATORS,
+    SafeASTVisitor,
+)
+from .data_sources import AVAILABLE_DATA_SOURCES
+from .novelty_codes import NOVELTY_CODES
+
+__all__ = [
+    # Main engine
+    "FormulaEngine",
+    "calculate_with_rule",
+    "get_available_sources_for_ui",
+    # Exceptions
+    "FormulaEngineError",
+    "TaxEngineError",
+    "ValidationError",
+    "CalculationError",
+    # Examples
+    "EXAMPLE_PROGRESSIVE_TAX_SCHEMA",
+    "EXAMPLE_IR_NICARAGUA_SCHEMA",  # Deprecated alias for backward compatibility
+    # Utilities
+    "to_decimal",
+    "safe_divide",
+    # AST modules
+    "ASTVisitor",
+    "SafeASTVisitor",
+    "ExpressionEvaluator",
+    "SAFE_OPERATORS",
+    "COMPARISON_OPERATORS",
+    "SAFE_FUNCTIONS",
+    "ALLOWED_AST_TYPES",
+    # Data sources
+    "AVAILABLE_DATA_SOURCES",
+    "NOVELTY_CODES",
+]

coati_payroll/formula_engine/ast/__init__.py

@@ -0,0 +1,110 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""AST parsing and evaluation modules.
+
+This package provides secure, enterprise-grade evaluation of mathematical
+expressions for payroll formulas. It implements a whitelist-based security
+model that prevents arbitrary code execution while maintaining financial precision.
+
+Security Architecture:
+
+1. **Whitelist-Based Validation**: Only explicitly approved AST node types
+   and functions are allowed. Any attempt to use unapproved operations is
+   rejected with a clear security violation message.
+
+2. **No Dynamic Code Execution**: The system does NOT use eval(), exec(),
+   compile(), or any dynamic method resolution (getattr). All code paths
+   are explicit and auditable.
+
+3. **DoS Prevention**: Expression length and AST depth are bounded to prevent
+   denial-of-service attacks via extremely long or deeply nested expressions.
+
+4. **Financial Precision**: All calculations use Python's Decimal type to
+   maintain precision required for payroll calculations.
+
+5. **Immutable Context**: Variable contexts are read-only during evaluation,
+   preventing side effects and ensuring deterministic results.
+
+Allowed Operations:
+- Arithmetic: +, -, *, /, //, %, **
+- Functions: min, max, abs, round
+- Variables: Pre-defined in execution context
+- Constants: Numeric literals only
+
+Prohibited Operations:
+- File I/O, network access, system calls
+- Import statements, attribute access
+- Lambda functions, list comprehensions
+- Any Python builtin not explicitly whitelisted
+
+Usage Example:
+    ```python
+    from coati_payroll.formula_engine.ast import ExpressionEvaluator
+    from decimal import Decimal
+
+    variables = {
+        'salario_base': Decimal('5000'),
+        'bono': Decimal('1000')
+    }
+
+    evaluator = ExpressionEvaluator(variables)
+    result = evaluator.evaluate('salario_base * 1.15 + bono')
+    # result = Decimal('6750')
+    ```
+
+Security Notes:
+- This module is designed for use with untrusted input (JSON rules)
+- All security validations are fail-safe (reject by default)
+- Adding new functions or operators requires security review
+- Regular security audits are recommended
+"""
+
+from .ast_visitor import ASTVisitor, SafeASTVisitor
+from .expression_evaluator import ExpressionEvaluator
+from .safe_operators import (
+    SAFE_OPERATORS,
+    COMPARISON_OPERATORS,
+    SAFE_FUNCTIONS,
+    ALLOWED_AST_TYPES,
+    MAX_EXPRESSION_LENGTH,
+    MAX_AST_DEPTH,
+    MAX_FUNCTION_ARGS,
+    validate_safe_function_call,
+)
+from .type_converter import (
+    to_decimal,
+    safe_divide,
+    MAX_DECIMAL_DIGITS,
+    MAX_DECIMAL_VALUE,
+    MIN_DECIMAL_VALUE,
+)
+
+__all__ = [
+    "ASTVisitor",
+    "SafeASTVisitor",
+    "ExpressionEvaluator",
+    "SAFE_OPERATORS",
+    "COMPARISON_OPERATORS",
+    "SAFE_FUNCTIONS",
+    "ALLOWED_AST_TYPES",
+    "MAX_EXPRESSION_LENGTH",
+    "MAX_AST_DEPTH",
+    "MAX_FUNCTION_ARGS",
+    "validate_safe_function_call",
+    "to_decimal",
+    "safe_divide",
+    "MAX_DECIMAL_DIGITS",
+    "MAX_DECIMAL_VALUE",
+    "MIN_DECIMAL_VALUE",
+]

coati_payroll/formula_engine/ast/ast_visitor.py

@@ -0,0 +1,259 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""AST Visitor pattern for safe expression evaluation.
+
+This module implements a secure AST visitor that evaluates mathematical expressions
+without using dynamic method dispatch (getattr). All node types are explicitly
+handled to prevent any possibility of code injection or unexpected behavior.
+
+Security Features:
+- Explicit visitor methods for each allowed node type
+- No dynamic method resolution (no getattr/setattr)
+- Whitelist-based approach - unknown nodes are rejected
+- All operations maintain Decimal precision
+- Division by zero is handled safely
+
+The visitor pattern ensures that only pre-approved AST node types can be processed,
+and each type has an explicit, auditable handler method.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from decimal import Decimal
+
+import ast
+
+from ..exceptions import CalculationError
+from .safe_operators import SAFE_FUNCTIONS, SAFE_OPERATORS
+from .type_converter import to_decimal
+
+
+class ASTVisitor(ABC):
+    """Visitor pattern base class for AST traversal.
+
+    This abstract base class defines the interface for AST visitors.
+    Implementations must provide a visit() method that safely evaluates
+    AST nodes and returns Decimal results.
+    """
+
+    @abstractmethod
+    def visit(self, node: ast.AST) -> Decimal:
+        """Visit and evaluate an AST node.
+
+        Args:
+            node: The AST node to visit and evaluate
+
+        Returns:
+            The evaluated result as a Decimal
+
+        Raises:
+            CalculationError: If the node cannot be safely evaluated
+        """
+        pass
+
+
+class SafeASTVisitor(ASTVisitor):
+    """Safe visitor for evaluating mathematical expressions.
+
+    This visitor implements a secure evaluation strategy:
+    1. Explicit dispatch - no dynamic method resolution
+    2. Whitelist approach - only known node types are processed
+    3. Immutable context - variables are read-only during evaluation
+    4. Decimal precision - all numeric operations maintain precision
+    5. Safe error handling - division by zero returns 0
+
+    Security Note:
+    This class does NOT use getattr() or any dynamic dispatch mechanism.
+    All node types are handled by explicit if/elif chains to prevent
+    any possibility of method injection or unexpected behavior.
+    """
+
+    def __init__(self, variables: dict[str, Decimal]):
+        """Initialize visitor with variable context.
+
+        Args:
+            variables: Dictionary of variable names to Decimal values.
+                      This dictionary is not modified during evaluation.
+        """
+        self.variables = variables
+
+    def visit(self, node: ast.AST) -> Decimal:
+        """Visit and evaluate an AST node using explicit dispatch.
+
+        This method uses explicit type checking with match/case instead of
+        dynamic method resolution (getattr) for security and maintainability.
+        Each node type is explicitly handled, making the code easier to audit
+        and preventing any possibility of method injection.
+
+        Args:
+            node: AST node to evaluate
+
+        Returns:
+            Decimal result of evaluation
+
+        Raises:
+            CalculationError: If the node type is not supported or evaluation fails
+        """
+        match node:
+            case ast.Constant():
+                return self.visit_constant(node)
+            case ast.Name():
+                return self.visit_name(node)
+            case ast.BinOp():
+                return self.visit_binop(node)
+            case ast.UnaryOp():
+                return self.visit_unaryop(node)
+            case ast.Call():
+                return self.visit_call(node)
+            case _:
+                raise CalculationError(
+                    f"Unsupported AST node type: {type(node).__name__}. "
+                    "Only Constant, Name, BinOp, UnaryOp, and Call nodes are allowed."
+                )
+
+    def visit_constant(self, node: ast.Constant) -> Decimal:
+        """Visit a constant node (numeric literal).
+
+        Args:
+            node: AST Constant node containing a numeric value
+
+        Returns:
+            The constant value as a Decimal
+
+        Raises:
+            CalculationError: If the constant cannot be converted to Decimal
+        """
+        return to_decimal(node.value)
+
+    def visit_name(self, node: ast.Name) -> Decimal:
+        """Visit a variable name node.
+
+        Args:
+            node: AST Name node representing a variable reference
+
+        Returns:
+            The value of the variable from the context
+
+        Raises:
+            CalculationError: If the variable is not defined in the context
+        """
+        if node.id not in self.variables:
+            raise CalculationError(
+                f"Undefined variable: '{node.id}'. " f"Available variables: {', '.join(sorted(self.variables.keys()))}"
+            )
+        return self.variables[node.id]
+
+    def visit_binop(self, node: ast.BinOp) -> Decimal:
+        """Visit a binary operation node (e.g., a + b, x * y).
+
+        Args:
+            node: AST BinOp node representing a binary operation
+
+        Returns:
+            The result of the binary operation as a Decimal
+
+        Raises:
+            CalculationError: If the operator is not whitelisted or operation fails
+        """
+        left = self.visit(node.left)
+        right = self.visit(node.right)
+
+        op_type = type(node.op)
+        op_func = SAFE_OPERATORS.get(op_type)
+        if not op_func:
+            raise CalculationError(
+                f"Operator '{op_type.__name__}' is not allowed. " f"Allowed operators: +, -, *, /, //, %, **"
+            )
+
+        if op_type in (ast.Div, ast.FloorDiv, ast.Mod) and right == 0:
+            return Decimal("0")
+
+        try:
+            result = op_func(left, right)
+            return to_decimal(result)
+        except (OverflowError, ValueError) as e:
+            raise CalculationError(f"Arithmetic error in operation '{left} {op_type.__name__} {right}': {e}") from e
+        except Exception as e:
+            raise CalculationError(f"Unexpected error in binary operation: {e}") from e
+
+    def visit_unaryop(self, node: ast.UnaryOp) -> Decimal:
+        """Visit a unary operation node (e.g., -x, +y).
+
+        Args:
+            node: AST UnaryOp node representing a unary operation
+
+        Returns:
+            The result of the unary operation as a Decimal
+
+        Raises:
+            CalculationError: If the unary operator is not allowed
+        """
+        operand = self.visit(node.operand)
+
+        op_type = type(node.op)
+        if op_type == ast.UAdd:
+            return to_decimal(+operand)
+        elif op_type == ast.USub:
+            return to_decimal(-operand)
+        else:
+            raise CalculationError(
+                f"Unary operator '{op_type.__name__}' is not allowed. " "Only unary + and - are permitted."
+            )
+
+    def visit_call(self, node: ast.Call) -> Decimal:
+        """Visit a function call node (e.g., max(a, b), round(x, 2)).
+
+        Args:
+            node: AST Call node representing a function call
+
+        Returns:
+            The result of the function call as a Decimal
+
+        Raises:
+            CalculationError: If the function is not whitelisted or call fails
+        """
+        if not isinstance(node.func, ast.Name):
+            raise CalculationError(
+                "Only direct named function calls are allowed. " "Attribute access and lambda functions are prohibited."
+            )
+
+        func_name = node.func.id
+        if func_name not in SAFE_FUNCTIONS:
+            raise CalculationError(
+                f"Function '{func_name}' is not in the whitelist. "
+                f"Allowed functions: {', '.join(sorted(SAFE_FUNCTIONS.keys()))}"
+            )
+
+        if node.keywords:
+            raise CalculationError(
+                f"Keyword arguments are not allowed in function '{func_name}'. " "Use positional arguments only."
+            )
+
+        args = [self.visit(arg) for arg in node.args]
+
+        try:
+            if func_name == "round" and len(args) > 1:
+                if args[1] < 0 or args[1] > 10:
+                    raise CalculationError(f"round() precision must be between 0 and 10, got {args[1]}")
+                result = SAFE_FUNCTIONS[func_name](args[0], int(args[1]))
+            else:
+                result = SAFE_FUNCTIONS[func_name](*args)
+            return to_decimal(result)
+        except TypeError as e:
+            raise CalculationError(f"Invalid arguments for function '{func_name}': {e}") from e
+        except ValueError as e:
+            raise CalculationError(f"Invalid value in function '{func_name}': {e}") from e
+        except Exception as e:
+            raise CalculationError(f"Error calling function '{func_name}': {e}") from e

coati_payroll/formula_engine/ast/expression_evaluator.py

@@ -0,0 +1,228 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Expression evaluator using AST visitor pattern.
+
+This module provides secure evaluation of mathematical expressions from JSON rules.
+It implements multiple layers of security:
+
+1. Expression Length Validation: Prevents DoS attacks via extremely long expressions
+2. AST Depth Validation: Prevents stack overflow from deeply nested expressions
+3. Whitelist-based AST Validation: Only approved node types are allowed
+4. Safe Visitor Pattern: No dynamic code execution or attribute access
+5. Decimal Precision: All calculations maintain financial precision
+
+Security Model:
+- Input expressions are parsed into Abstract Syntax Trees (AST)
+- AST is validated against a whitelist of allowed node types
+- AST depth is checked to prevent stack overflow
+- Evaluation uses explicit visitor pattern (no eval/exec/compile)
+- All operations are deterministic and side-effect free
+
+Example Safe Expression:
+    'salario_base * 1.15 + max(bono, 1000)'
+
+Example Unsafe Expression (rejected):
+    '__import__("os").system("rm -rf /")'
+    'open("/etc/passwd").read()'
+    '[x for x in range(1000000)]'
+"""
+
+from __future__ import annotations
+
+import ast
+from decimal import Decimal
+from typing import Callable
+
+from coati_payroll.i18n import _
+from coati_payroll.log import TRACE_LEVEL_NUM, is_trace_enabled, log
+
+from ..exceptions import CalculationError
+from .ast_visitor import SafeASTVisitor
+from .safe_operators import ALLOWED_AST_TYPES, MAX_EXPRESSION_LENGTH, MAX_AST_DEPTH
+from .type_converter import to_decimal
+
+
+class ExpressionEvaluator:
+    """Evaluates mathematical expressions safely using AST.
+
+    This class provides enterprise-grade secure expression evaluation for
+    payroll formulas. It prevents code injection, DoS attacks, and ensures
+    all calculations are deterministic and auditable.
+
+    Security Features:
+    - Expression length limits (prevents DoS)
+    - AST depth limits (prevents stack overflow)
+    - Whitelist-based validation (prevents code injection)
+    - No dynamic code execution (no eval/exec/compile)
+    - Immutable variable context (prevents side effects)
+    - Comprehensive error messages for debugging
+
+    Thread Safety:
+    This class is thread-safe as long as the variables dictionary is not
+    modified during evaluation. Each evaluation creates a new visitor instance.
+    """
+
+    def __init__(self, variables: dict[str, Decimal], trace_callback: Callable[[str], None] | None = None):
+        """Initialize expression evaluator.
+
+        Args:
+            variables: Dictionary of variable names to Decimal values.
+                      This dictionary is not modified during evaluation.
+            trace_callback: Optional callback for trace logging.
+                          Should be thread-safe if used in concurrent contexts.
+        """
+        self.variables = variables
+        self.trace_callback = trace_callback or self._default_trace
+
+    def _default_trace(self, message: str) -> None:
+        """Default trace callback."""
+        if is_trace_enabled():
+            try:
+                log.log(TRACE_LEVEL_NUM, message)
+            except Exception:
+                pass
+
+    def evaluate(self, expression: str) -> Decimal:
+        """Safely evaluate a mathematical expression using AST.
+
+        This method implements multiple layers of security validation:
+        1. Input validation (type, length)
+        2. Syntax validation (AST parsing)
+        3. Security validation (whitelist checking)
+        4. Depth validation (stack overflow prevention)
+        5. Safe evaluation (visitor pattern)
+
+        Args:
+            expression: Mathematical expression string (e.g., 'a + b * 2')
+
+        Returns:
+            Result of the expression as Decimal
+
+        Raises:
+            CalculationError: If expression is invalid, unsafe, or evaluation fails
+
+        Examples:
+            >>> evaluator = ExpressionEvaluator({'x': Decimal('10'), 'y': Decimal('5')})
+            >>> evaluator.evaluate('x + y')
+            Decimal('15')
+            >>> evaluator.evaluate('max(x, y) * 2')
+            Decimal('20')
+        """
+        if not expression or not isinstance(expression, str):
+            return Decimal("0")
+
+        expression = expression.strip()
+        if not expression:
+            return Decimal("0")
+
+        if len(expression) > MAX_EXPRESSION_LENGTH:
+            raise CalculationError(
+                f"Expression too long ({len(expression)} characters). "
+                f"Maximum allowed: {MAX_EXPRESSION_LENGTH} characters. "
+                "This limit prevents denial-of-service attacks."
+            )
+
+        self.trace_callback(_("Evaluando expresión: '%(expr)s'") % {"expr": expression})
+
+        try:
+            tree = ast.parse(expression, mode="eval")
+
+            self._validate_ast_security(tree.body)
+            self._validate_ast_depth(tree.body)
+
+            visitor = SafeASTVisitor(self.variables)
+            result = visitor.visit(tree.body)
+            final_result = to_decimal(result)
+
+            self.trace_callback(
+                _("Resultado expresión '%(expr)s' => %(res)s") % {"expr": expression, "res": final_result}
+            )
+            return final_result
+        except SyntaxError as e:
+            raise CalculationError(
+                f"Invalid expression syntax in '{expression}': {e}. "
+                "Check for unmatched parentheses, invalid operators, or typos."
+            ) from e
+        except ZeroDivisionError:
+            return Decimal("0")
+        except CalculationError:
+            raise
+        except Exception as e:
+            raise CalculationError(f"Unexpected error evaluating expression '{expression}': {e}") from e
+
+    def _validate_ast_security(self, node: ast.AST) -> None:
+        """Validate that an AST node only contains safe operations.
+
+        This method implements a whitelist-based security model. It walks the
+        entire AST and verifies that every node is in the allowed list. This
+        prevents code injection attacks like:
+        - Import statements: __import__('os').system('rm -rf /')
+        - Attribute access: obj.__class__.__bases__[0].__subclasses__()
+        - List comprehensions: [x for x in range(999999999)]
+        - Lambda functions: (lambda: exec('malicious code'))()
+
+        Args:
+            node: AST node to validate (typically the root of the expression tree)
+
+        Raises:
+            CalculationError: If any unsafe operation is detected
+        """
+        for child in ast.walk(node):
+            if not isinstance(child, ALLOWED_AST_TYPES):
+                raise CalculationError(
+                    f"Security violation: AST node type '{child.__class__.__name__}' is not allowed. "
+                    "Only basic arithmetic operations and whitelisted functions are permitted. "
+                    "This restriction prevents code injection and arbitrary code execution."
+                )
+
+            if isinstance(child, ast.Call):
+                if not isinstance(child.func, ast.Name):
+                    raise CalculationError(
+                        "Security violation: Only direct named function calls are allowed. "
+                        "Attribute access (e.g., obj.method()) and lambda functions are prohibited."
+                    )
+                from .safe_operators import SAFE_FUNCTIONS
+
+                if child.func.id not in SAFE_FUNCTIONS:
+                    raise CalculationError(
+                        f"Security violation: Function '{child.func.id}' is not in the whitelist. "
+                        f"Allowed functions: {', '.join(sorted(SAFE_FUNCTIONS.keys()))}. "
+                        "This restriction prevents execution of arbitrary Python functions."
+                    )
+
+    def _validate_ast_depth(self, node: ast.AST, current_depth: int = 0) -> None:
+        """Validate that AST depth does not exceed maximum to prevent stack overflow.
+
+        Deeply nested expressions can cause stack overflow during evaluation:
+        - Example: ((((((((((x + 1) + 1) + 1) + 1) + 1) + 1) + 1) + 1) + 1) + 1)
+
+        This validation prevents denial-of-service attacks via deeply nested
+        expressions that could exhaust the call stack.
+
+        Args:
+            node: AST node to validate
+            current_depth: Current depth in the tree (used for recursion)
+
+        Raises:
+            CalculationError: If AST depth exceeds maximum allowed
+        """
+        if current_depth > MAX_AST_DEPTH:
+            raise CalculationError(
+                f"Expression too complex: AST depth ({current_depth}) exceeds maximum ({MAX_AST_DEPTH}). "
+                "Simplify the expression by breaking it into multiple steps. "
+                "This limit prevents stack overflow attacks."
+            )
+
+        for child in ast.iter_child_nodes(node):
+            self._validate_ast_depth(child, current_depth + 1)