coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/report_export.py

@@ -0,0 +1,208 @@
+# 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.
+"""Report export functionality for Excel format.
+
+Provides utilities to export report results to Excel files with proper
+formatting and metadata.
+"""
+
+from __future__ import annotations
+
+# <-------------------------------------------------------------------------> #
+# Standard library
+# <-------------------------------------------------------------------------> #
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+# <-------------------------------------------------------------------------> #
+# Third party libraries
+# <-------------------------------------------------------------------------> #
+try:
+    from openpyxl import Workbook
+    from openpyxl.styles import Font, Alignment, PatternFill
+    from openpyxl.utils import get_column_letter
+
+    OPENPYXL_AVAILABLE = True
+except ImportError:
+    OPENPYXL_AVAILABLE = False
+
+
+# <-------------------------------------------------------------------------> #
+# Local modules
+# <-------------------------------------------------------------------------> #
+from coati_payroll.config import DIRECTORIO_APP
+from coati_payroll.log import log
+
+
+class ReportExporter:
+    """Handles exporting report results to various formats."""
+
+    def __init__(self, report_name: str, results: List[Dict[str, Any]]):
+        """Initialize exporter.
+
+        Args:
+            report_name: Name of the report
+            results: List of result dictionaries
+        """
+        self.report_name = report_name
+        self.results = results
+
+    def to_excel(self, output_path: Optional[str] = None) -> str:
+        """Export results to Excel format.
+
+        Args:
+            output_path: Optional output file path. If not provided, generates one.
+
+        Returns:
+            Path to exported file
+
+        Raises:
+            ImportError: If openpyxl is not installed
+        """
+        if not OPENPYXL_AVAILABLE:
+            raise ImportError("openpyxl is required for Excel export. " "Install it with: pip install openpyxl")
+
+        # Generate output path if not provided
+        if not output_path:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            safe_name = "".join(c for c in self.report_name if c.isalnum() or c in (" ", "_", "-")).strip()
+            safe_name = safe_name.replace(" ", "_")  # Replace spaces with underscores for Windows compatibility
+            filename = f"{safe_name}_{timestamp}.xlsx"
+
+            # Create exports directory if it doesn't exist
+            exports_dir = Path(DIRECTORIO_APP) / "exports" / "reports"
+            exports_dir.mkdir(parents=True, exist_ok=True)
+
+            output_path = str((exports_dir / filename).absolute())
+
+        # Create workbook
+        wb = Workbook()
+        ws = wb.active
+        ws.title = self.report_name[:31]  # Excel sheet name limit
+
+        # Add metadata
+        ws["A1"] = "Report:"
+        ws["B1"] = self.report_name
+        ws["A2"] = "Generated:"
+        ws["B2"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        ws["A3"] = "Total Records:"
+        ws["B3"] = len(self.results)
+
+        # Style metadata
+        for cell in ["A1", "A2", "A3"]:
+            ws[cell].font = Font(bold=True)
+
+        # Add blank row
+        start_row = 5
+
+        if self.results:
+            # Add headers
+            headers = list(self.results[0].keys())
+            for col_idx, header in enumerate(headers, start=1):
+                cell = ws.cell(row=start_row, column=col_idx, value=header)
+                cell.font = Font(bold=True, color="FFFFFF")
+                cell.fill = PatternFill(start_color="366092", end_color="366092", fill_type="solid")
+                cell.alignment = Alignment(horizontal="center", vertical="center")
+
+            # Add data
+            for row_idx, row_data in enumerate(self.results, start=start_row + 1):
+                for col_idx, header in enumerate(headers, start=1):
+                    value = row_data.get(header)
+                    ws.cell(row=row_idx, column=col_idx, value=value)
+
+            # Auto-adjust column widths
+            for col_idx, header in enumerate(headers, start=1):
+                column_letter = get_column_letter(col_idx)
+                max_length = len(str(header))
+
+                for row_data in self.results:
+                    value = row_data.get(header)
+                    if value is not None:
+                        max_length = max(max_length, len(str(value)))
+
+                # Set width with some padding
+                adjusted_width = min(max_length + 2, 50)  # Max 50 chars
+                ws.column_dimensions[column_letter].width = adjusted_width
+
+        # Save workbook
+        wb.save(output_path)
+        log.info(f"Report exported to: {output_path}")
+
+        return output_path
+
+    def to_csv(self, output_path: Optional[str] = None) -> str:
+        """Export results to CSV format.
+
+        Args:
+            output_path: Optional output file path
+
+        Returns:
+            Path to exported file
+        """
+        import csv
+
+        # Generate output path if not provided
+        if not output_path:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            safe_name = "".join(c for c in self.report_name if c.isalnum() or c in (" ", "_", "-")).strip()
+            safe_name = safe_name.replace(" ", "_")  # Replace spaces with underscores for Windows compatibility
+            filename = f"{safe_name}_{timestamp}.csv"
+
+            exports_dir = Path(DIRECTORIO_APP) / "exports" / "reports"
+            exports_dir.mkdir(parents=True, exist_ok=True)
+
+            output_path = str((exports_dir / filename).absolute())
+
+        # Write CSV
+        if self.results:
+            headers = list(self.results[0].keys())
+
+            with open(output_path, "w", newline="", encoding="utf-8") as csvfile:
+                writer = csv.DictWriter(csvfile, fieldnames=headers)
+                writer.writeheader()
+                writer.writerows(self.results)
+
+        log.info(f"Report exported to: {output_path}")
+        return output_path
+
+
+def export_report_to_excel(report_name: str, results: List[Dict[str, Any]], output_path: Optional[str] = None) -> str:
+    """Convenience function to export report to Excel.
+
+    Args:
+        report_name: Name of the report
+        results: Report results
+        output_path: Optional output path
+
+    Returns:
+        Path to exported file
+    """
+    exporter = ReportExporter(report_name, results)
+    return exporter.to_excel(output_path)
+
+
+def export_report_to_csv(report_name: str, results: List[Dict[str, Any]], output_path: Optional[str] = None) -> str:
+    """Convenience function to export report to CSV.
+
+    Args:
+        report_name: Name of the report
+        results: Report results
+        output_path: Optional output path
+
+    Returns:
+        Path to exported file
+    """
+    exporter = ReportExporter(report_name, results)
+    return exporter.to_csv(output_path)

coati_payroll/schema_validator.py

@@ -0,0 +1,167 @@
+# 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.
+"""Schema validation for formula engine calculation rules.
+
+This module provides validation functions for JSON schemas used by the
+FormulaEngine to ensure they have the correct structure before execution.
+"""
+
+from __future__ import annotations
+
+# <-------------------------------------------------------------------------> #
+# Standard library
+# <-------------------------------------------------------------------------> #
+import ast
+from typing import Any, Type
+
+# <-------------------------------------------------------------------------> #
+# Third party libraries
+# <-------------------------------------------------------------------------> #
+
+# <-------------------------------------------------------------------------> #
+# Local modules
+# <-------------------------------------------------------------------------> #
+from coati_payroll.enums import StepType
+
+__all__ = ["ValidationError", "validate_schema", "validate_schema_deep"]
+
+
+class ValidationError(Exception):
+    """Exception for validation errors in schema or data."""
+
+    pass
+
+
+def validate_schema(schema: dict[str, Any], error_class: Type[Exception] = ValidationError) -> None:
+    """Validate the calculation schema structure.
+
+    Args:
+        schema: The JSON schema to validate
+
+    Raises:
+        ValidationError: If schema is missing required fields or has invalid structure
+    """
+    if not isinstance(schema, dict):
+        raise error_class("Schema must be a dictionary")
+
+    # Check for required sections
+    if "steps" not in schema:
+        raise error_class("Schema must contain 'steps' section")
+
+    # Validate steps structure
+    for i, step in enumerate(schema.get("steps", [])):
+        if not isinstance(step, dict):
+            raise error_class(f"Step {i} must be a dictionary")
+        if "name" not in step:
+            raise error_class(f"Step {i} must have a 'name' field")
+        if "type" not in step:
+            raise error_class(f"Step {i} must have a 'type' field")
+
+
+def validate_schema_deep(schema: dict[str, Any], error_class: Type[Exception] = ValidationError) -> None:
+    """Validate the calculation schema structure including formula safety.
+
+    This performs deeper validation than validate_schema, including checking
+    formulas for unsafe operations. Use this for API validation endpoints.
+
+    Args:
+        schema: The JSON schema to validate
+        error_class: Exception class to raise on error
+
+    Raises:
+        ValidationError: If schema is invalid or contains unsafe formulas
+    """
+    # First do basic validation
+    validate_schema(schema, error_class)
+
+    # Get valid step types
+    valid_step_types = {step_type.value for step_type in StepType}
+
+    # Then validate step types and formulas for safety
+    for i, step in enumerate(schema.get("steps", [])):
+        step_type = step.get("type")
+
+        # Validate step type
+        if step_type not in valid_step_types:
+            raise error_class(
+                f"Step {i} has invalid type '{step_type}'. Valid types are: {', '.join(valid_step_types)}"
+            )
+
+        # Validate formulas for calculation steps
+        if step_type == StepType.CALCULATION:
+            formula = step.get("formula", "")
+            if formula:
+                _validate_formula_safety(formula, error_class)
+
+        # Validate conditional step formulas
+        if step_type == StepType.CONDITIONAL:
+            if_true = step.get("if_true", "")
+            if_false = step.get("if_false", "")
+            if if_true:
+                _validate_formula_safety(if_true, error_class)
+            if if_false:
+                _validate_formula_safety(if_false, error_class)
+
+
+def _validate_formula_safety(formula: str, error_class: Type[Exception] = ValidationError) -> None:
+    """Validate that a formula doesn't contain unsafe operations.
+
+    Args:
+        formula: Formula string to validate
+        error_class: Exception class to raise on error
+
+    Raises:
+        ValidationError: If formula contains unsafe operations
+    """
+    if not formula or not isinstance(formula, str):
+        return
+
+    try:
+        # Parse the formula into an AST
+        tree = ast.parse(formula, mode="eval")
+
+        # Check for unsafe operations
+        for node in ast.walk(tree.body):
+            # Block dangerous operations
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                raise error_class("Import statements are not allowed in formulas")
+
+            # Block attribute access (prevents __import__, etc.)
+            if isinstance(node, ast.Attribute):
+                raise error_class("Attribute access is not allowed in formulas")
+
+            # Block function calls to __import__ and other dangerous builtins
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+                func_name = node.func.id
+                dangerous_functions = {
+                    "__import__",
+                    "eval",
+                    "exec",
+                    "compile",
+                    "open",
+                    "input",
+                    "__builtins__",
+                    "globals",
+                    "locals",
+                    "vars",
+                    "dir",
+                    "getattr",
+                    "setattr",
+                    "delattr",
+                    "hasattr",
+                }
+                if func_name in dangerous_functions:
+                    raise error_class(f"Function '{func_name}' is not allowed in formulas")
+    except SyntaxError as e:
+        raise error_class(f"Invalid formula syntax: {e}") from e

coati_payroll/security.py

@@ -0,0 +1,77 @@
+# 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.
+"""Security module - HTTP Security Headers and Security Utilities.
+
+This module implements security best practices for Flask applications,
+including HTTP security headers to protect against common web vulnerabilities.
+"""
+
+from __future__ import annotations
+
+
+def configure_security_headers(app):
+    """Configure HTTP security headers for the Flask application.
+
+    Implements OWASP recommendations for secure HTTP headers:
+    - Content-Security-Policy: Prevents XSS and data injection attacks
+    - X-Frame-Options: Prevents clickjacking attacks
+    - X-Content-Type-Options: Prevents MIME sniffing
+    - Strict-Transport-Security: Forces HTTPS connections (production only)
+    - X-XSS-Protection: Legacy XSS protection for older browsers
+    - Referrer-Policy: Controls referrer information leakage
+
+    Args:
+        app: Flask application instance
+    """
+    from coati_payroll.config import DESARROLLO
+
+    @app.after_request
+    def add_security_headers(response):
+        """Add security headers to all responses."""
+
+        # Content Security Policy - Restricts resource loading
+        # Allows self-hosted resources and specific external sources
+        csp = (
+            "default-src 'self'; "
+            "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net; "
+            "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+            "img-src 'self' data: https:; "
+            "font-src 'self' data: https://cdn.jsdelivr.net; "
+            "connect-src 'self'; "
+            "frame-ancestors 'none'; "
+            "base-uri 'self'; "
+            "form-action 'self'"
+        )
+        response.headers["Content-Security-Policy"] = csp
+
+        # Prevent clickjacking - don't allow framing by any site
+        response.headers["X-Frame-Options"] = "DENY"
+
+        # Prevent MIME type sniffing
+        response.headers["X-Content-Type-Options"] = "nosniff"
+
+        # Legacy XSS protection (for older browsers)
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+
+        # Control referrer information
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+
+        # HSTS - Force HTTPS (only in production, never in testing)
+        enable_hsts = not DESARROLLO and not app.config.get("TESTING", False)
+        if enable_hsts:
+            response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+
+        return response
+
+    return app