omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/cli/commands.py

@@ -0,0 +1,216 @@
+"""
+ONEX Infrastructure CLI Commands.
+
+Provides CLI interface for infrastructure management and validation.
+"""
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@click.group()
+def cli() -> None:
+    """ONEX Infrastructure CLI."""
+
+
+@cli.group()
+def validate() -> None:
+    """Validation commands for infrastructure code."""
+
+
+@validate.command("architecture")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--max-violations",
+    default=None,
+    help="Maximum allowed violations (default: INFRA_MAX_VIOLATIONS)",
+)
+def validate_architecture_cmd(directory: str, max_violations: int | None) -> None:
+    """Validate architecture (one-model-per-file)."""
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_MAX_VIOLATIONS,
+        validate_infra_architecture,
+    )
+
+    console.print(f"[bold blue]Validating architecture in {directory}...[/bold blue]")
+    # Use INFRA_MAX_VIOLATIONS constant if no override provided
+    effective_max_violations = (
+        max_violations if max_violations is not None else INFRA_MAX_VIOLATIONS
+    )
+    result = validate_infra_architecture(directory, effective_max_violations)
+    _print_result("Architecture", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("contracts")
+@click.argument("directory", default="src/omnibase_infra/nodes/")
+def validate_contracts_cmd(directory: str) -> None:
+    """Validate YAML contracts."""
+    from omnibase_infra.validation.infra_validators import validate_infra_contracts
+
+    console.print(f"[bold blue]Validating contracts in {directory}...[/bold blue]")
+    result = validate_infra_contracts(directory)
+    _print_result("Contracts", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("patterns")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--strict/--no-strict",
+    default=None,
+    help="Enable strict mode (default: INFRA_PATTERNS_STRICT)",
+)
+def validate_patterns_cmd(directory: str, strict: bool | None) -> None:
+    """Validate code patterns and naming conventions."""
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_PATTERNS_STRICT,
+        validate_infra_patterns,
+    )
+
+    console.print(f"[bold blue]Validating patterns in {directory}...[/bold blue]")
+    # Use INFRA_PATTERNS_STRICT constant if no override provided
+    effective_strict = strict if strict is not None else INFRA_PATTERNS_STRICT
+    result = validate_infra_patterns(directory, effective_strict)
+    _print_result("Patterns", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("unions")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--max-unions",
+    default=None,
+    help="Maximum allowed union count (default: INFRA_MAX_UNIONS)",
+)
+@click.option(
+    "--strict/--no-strict",
+    default=None,
+    help="Enable strict mode (default: INFRA_UNIONS_STRICT)",
+)
+def validate_unions_cmd(
+    directory: str, max_unions: int | None, strict: bool | None
+) -> None:
+    """Validate Union type usage.
+
+    Counts total unions in the codebase.
+    Valid `X | None` patterns are counted but not flagged as violations.
+    """
+    from omnibase_infra.validation.infra_validators import (
+        INFRA_MAX_UNIONS,
+        INFRA_UNIONS_STRICT,
+        validate_infra_union_usage,
+    )
+
+    console.print(f"[bold blue]Validating union usage in {directory}...[/bold blue]")
+    # Use constants if no override provided
+    effective_max_unions = max_unions if max_unions is not None else INFRA_MAX_UNIONS
+    effective_strict = strict if strict is not None else INFRA_UNIONS_STRICT
+    result = validate_infra_union_usage(
+        directory, effective_max_unions, effective_strict
+    )
+    _print_result("Union Usage", result)
+    raise SystemExit(0 if result.is_valid else 1)
+
+
+@validate.command("imports")
+@click.argument("directory", default="src/omnibase_infra/")
+def validate_imports_cmd(directory: str) -> None:
+    """Check for circular imports."""
+    from omnibase_infra.validation.infra_validators import (
+        validate_infra_circular_imports,
+    )
+
+    console.print(f"[bold blue]Checking circular imports in {directory}...[/bold blue]")
+    result = validate_infra_circular_imports(directory)
+
+    # ModelImportValidationResult uses has_circular_imports property (plural)
+    if not result.has_circular_imports:
+        console.print("[bold green]Circular Imports: PASS[/bold green]")
+        raise SystemExit(0)
+    console.print("[bold red]Circular Imports: FAIL[/bold red]")
+    if hasattr(result, "cycles") and result.cycles:
+        for cycle in result.cycles:
+            console.print(f"  [red]Cycle: {cycle}[/red]")
+    if hasattr(result, "errors") and result.errors:
+        for error in result.errors:
+            console.print(f"  [red]{error}[/red]")
+    raise SystemExit(1)
+
+
+@validate.command("all")
+@click.argument("directory", default="src/omnibase_infra/")
+@click.option(
+    "--nodes-dir", default="src/omnibase_infra/nodes/", help="Nodes directory"
+)
+def validate_all_cmd(directory: str, nodes_dir: str) -> None:
+    """Run all validations."""
+    from omnibase_infra.validation.infra_validators import (
+        get_validation_summary,
+        validate_infra_all,
+    )
+
+    console.print(f"[bold blue]Running all validations on {directory}...[/bold blue]\n")
+    results = validate_infra_all(directory, nodes_dir)
+    summary = get_validation_summary(results)
+
+    # Create summary table
+    table = Table(title="Validation Results")
+    table.add_column("Validator", style="cyan")
+    table.add_column("Status", style="bold")
+    table.add_column("Errors", style="red")
+
+    for name, result in results.items():
+        is_valid = _is_result_valid(result)
+        error_count = _get_error_count(result)
+        status = "[green]PASS[/green]" if is_valid else "[red]FAIL[/red]"
+        table.add_row(name.replace("_", " ").title(), status, str(error_count))
+
+    console.print(table)
+
+    # Print summary
+    passed = summary.get("passed", 0)
+    total = summary.get("total_validators", 0)
+    console.print(f"\n[bold]Summary: {passed}/{total} passed[/bold]")
+
+    all_valid = summary.get("failed", 0) == 0
+    raise SystemExit(0 if all_valid else 1)
+
+
+def _is_result_valid(result: object) -> bool:
+    """Check if a validation result is valid."""
+    if hasattr(result, "has_circular_imports"):
+        return not bool(result.has_circular_imports)
+    if hasattr(result, "is_valid"):
+        return bool(result.is_valid)
+    return False
+
+
+def _get_error_count(result: object) -> int:
+    """Get the error count from a validation result."""
+    if hasattr(result, "has_circular_imports"):
+        if hasattr(result, "cycles"):
+            return len(result.cycles)
+        return 1 if result.has_circular_imports else 0
+    if hasattr(result, "errors"):
+        return len(result.errors)
+    return 0
+
+
+def _print_result(name: str, result: object) -> None:
+    """Print validation result with rich formatting."""
+    if hasattr(result, "is_valid"):
+        if result.is_valid:
+            console.print(f"[bold green]{name}: PASS[/bold green]")
+        else:
+            console.print(f"[bold red]{name}: FAIL[/bold red]")
+            if hasattr(result, "errors") and result.errors:
+                for error in result.errors:
+                    console.print(f"  [red]{error}[/red]")
+
+
+if __name__ == "__main__":
+    cli()

omnibase_infra/configs/widget_mapping.yaml

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# Widget Mapping Configuration for ONEX Registry Dashboard
+#
+# This file defines the mapping from node capabilities and semantic roles
+# to dashboard widget types. Used by the Registry API to inform dashboards
+# which widget to render for each node.
+#
+# Related Tickets:
+#   - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+#
+# Widget Types:
+#   - status_indicator: Shows health/state with colored indicator
+#   - event_feed: Scrolling list of recent events
+#   - metric_card: Single metric with value and optional trend
+#   - info_card: General information display
+#   - status_grid: Grid of status indicators
+#   - timeline: Time-based visualization
+#   - gauge: Circular progress/threshold indicator
+#   - table: Tabular data display
+#
+# Configuration Sections:
+#   - version: Schema version for compatibility checking
+#   - capability_mappings: Maps capability tags to widget configs
+#   - semantic_mappings: Maps semantic roles to widget configs
+#   - fallback: Default config when no mapping matches
+version: "1.0.0"
+# Capability Mappings
+# Map specific capability tags to widget configurations.
+# These take precedence over semantic mappings.
+capability_mappings:
+  # Health and monitoring capabilities
+  health.check:
+    widget_type: status_indicator
+    defaults:
+      show_timestamp: true
+      refresh_interval_seconds: 10
+  health.heartbeat:
+    widget_type: status_indicator
+    defaults:
+      show_timestamp: true
+      show_last_seen: true
+  # Event-related capabilities
+  event.emit:
+    widget_type: event_feed
+    defaults:
+      max_items: 50
+      show_timestamp: true
+      auto_scroll: true
+  event.consume:
+    widget_type: event_feed
+    defaults:
+      max_items: 50
+      show_source: true
+  event.transform:
+    widget_type: timeline
+    defaults:
+      show_duration: true
+  # Kafka/messaging capabilities
+  kafka.consumer:
+    widget_type: metric_card
+    defaults:
+      refresh_interval_seconds: 5
+      show_lag: true
+  kafka.producer:
+    widget_type: metric_card
+    defaults:
+      refresh_interval_seconds: 5
+      show_throughput: true
+  kafka.stream:
+    widget_type: timeline
+    defaults:
+      show_offset: true
+  # Database capabilities
+  postgres.storage:
+    widget_type: metric_card
+    defaults:
+      show_connection_count: true
+      refresh_interval_seconds: 10
+  postgres.query:
+    widget_type: table
+    defaults:
+      show_query_time: true
+  # Service discovery
+  consul.register:
+    widget_type: status_indicator
+    defaults:
+      show_service_id: true
+  consul.discover:
+    widget_type: status_grid
+    defaults:
+      show_health: true
+      group_by: service_name
+  # Workflow capabilities
+  workflow.orchestrate:
+    widget_type: timeline
+    defaults:
+      show_steps: true
+      show_duration: true
+  workflow.reduce:
+    widget_type: gauge
+    defaults:
+      show_progress: true
+  # Compute capabilities
+  compute.transform:
+    widget_type: metric_card
+    defaults:
+      show_throughput: true
+      show_latency: true
+  compute.validate:
+    widget_type: status_indicator
+    defaults:
+      show_pass_rate: true
+  # Effect capabilities
+  effect.http:
+    widget_type: metric_card
+    defaults:
+      show_latency: true
+      show_error_rate: true
+  effect.grpc:
+    widget_type: metric_card
+    defaults:
+      show_latency: true
+      show_error_rate: true
+# Semantic Mappings
+# Map semantic roles/contexts to widget configurations.
+# Used when capability_mappings don't match.
+semantic_mappings:
+  # Node overview in dashboard
+  node_overview:
+    widget_type: info_card
+    defaults:
+      show_version: true
+      show_capabilities: true
+      show_state: true
+  # Instance health grid
+  instance_health:
+    widget_type: status_grid
+    defaults:
+      group_by: service_name
+      show_address: true
+      show_port: true
+  # Registration timeline
+  registration_timeline:
+    widget_type: timeline
+    defaults:
+      show_state_transitions: true
+      show_timestamps: true
+  # Capability matrix
+  capability_matrix:
+    widget_type: table
+    defaults:
+      group_by: node_type
+      show_capability_tags: true
+  # Summary statistics
+  summary_stats:
+    widget_type: metric_card
+    defaults:
+      show_trend: true
+      compare_to_previous: true
+  # Error monitoring
+  error_monitoring:
+    widget_type: event_feed
+    defaults:
+      filter_level: error
+      max_items: 100
+      highlight_critical: true
+# Fallback Configuration
+# Used when no capability or semantic mapping matches.
+fallback:
+  widget_type: info_card
+  defaults:
+    show_name: true
+    show_state: true
+    show_type: true

omnibase_infra/constants_topic_patterns.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Topic pattern constants for event bus topic validation.
+
+This module provides shared regex patterns for validating event bus topic names.
+These patterns are used across multiple modules (e.g., MixinConsulTopicIndex,
+MixinNodeIntrospection) to ensure consistent topic validation.
+
+Note:
+    This module is intentionally dependency-free (no imports from omnibase_infra)
+    to avoid circular import issues. Keep it that way.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+# Topic name pattern: alphanumeric, underscores, hyphens, and periods only.
+# This matches Kafka/Redpanda topic naming conventions and ensures safe
+# interpolation into Consul KV paths (prevents path traversal via slashes).
+# Pattern: ^[a-zA-Z0-9._-]+$
+TOPIC_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-zA-Z0-9._-]+$")
+
+
+__all__: list[str] = ["TOPIC_NAME_PATTERN"]

omnibase_infra/contracts/handlers/filesystem/handler_contract.yaml

@@ -0,0 +1,264 @@
+# Handler ID follows convention: {node_type}.{domain}.handler
+handler_id: effect.filesystem.handler
+name: FileSystem Handler
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+description: >
+  Effect handler for filesystem operations including read, write, list, delete, and directory management.
+
+descriptor:
+  node_archetype: effect
+  purity: side_effecting
+  # Idempotent: false because write operations may append (non-idempotent).
+  # Individual operations (write w/ overwrite, mkdir w/ exist_ok) can be
+  # idempotent, but the handler as a whole supports non-idempotent semantics.
+  idempotent: false
+  # TIMEOUT CONFIGURATION (30 seconds)
+  # ---------------------------------
+  # While typical local filesystem I/O completes in milliseconds, 30 seconds
+  # accommodates these legitimate scenarios:
+  #
+  # 1. Network-mounted filesystems (NFS, CIFS, SSHFS) with latency up to seconds
+  # 2. Large file operations: max_file_size_bytes (10MB) on slow storage
+  # 3. Container volume mounts with additional abstraction overhead
+  # 4. High disk I/O contention in shared infrastructure environments
+  # 5. Spinning disk storage (HDDs) vs SSDs in mixed deployments
+  #
+  # OVERRIDE GUIDANCE:
+  # - Reduce to 5000ms for latency-sensitive, local-only deployments
+  # - Increase to 60000ms for known slow NAS/SAN storage
+  # - Consider per-operation timeouts in handler implementation for fine-grained control
+  #
+  # CIRCUIT BREAKER RELATIONSHIP:
+  # Circuit breaker timeout (60000ms) is intentionally 2x handler timeout to ensure:
+  # - Individual operations timeout before circuit evaluation
+  # - Circuit tracks failure patterns, not just slow operations
+  # - Proper failure sequence: timeout → retry exhaustion → circuit threshold
+  timeout_ms: 30000
+  retry_policy:
+    enabled: true
+    max_retries: 3
+    backoff_strategy: exponential
+    base_delay_ms: 500
+    max_delay_ms: 10000
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    # Reset timeout: 60s = 2x handler timeout_ms (30s). This ensures the circuit
+    # stays open long enough for transient issues to resolve while allowing
+    # recovery attempts. See timeout_ms comment above for relationship details.
+    timeout_ms: 60000
+  # Serialized: Prevents race conditions for write operations to same file.
+  # Read-only operations could use concurrent policy, but handler scope
+  # includes writes so we use serialized for safety.
+  concurrency_policy: serialized
+  isolation_policy: none
+  observability_level: standard
+capability_outputs:
+  - filesystem.read
+  - filesystem.write
+  - filesystem.list
+  - filesystem.delete
+  - filesystem.mkdir
+# NOTE: Models defined in OMN-1160 (FileSystemHandler Contract)
+input_model: omnibase_infra.handlers.filesystem.ModelFileSystemRequest
+output_model: omnibase_infra.handlers.filesystem.ModelFileSystemResult
+supports_lifecycle: true
+supports_health_check: true
+supports_provisioning: false
+tags:
+  - filesystem
+  - effect
+  - infrastructure
+metadata:
+  author: OmniNode Team
+  ticket: OMN-1160
+  security:
+    # =========================================================================
+    # SECURITY CONFIGURATION
+    # =========================================================================
+    # This section defines comprehensive security constraints for filesystem
+    # operations. Implementers MUST enforce all constraints documented here.
+    # =========================================================================
+
+    # -------------------------------------------------------------------------
+    # PATH RESTRICTIONS
+    # -------------------------------------------------------------------------
+    # SECURITY: Handler implementation MUST enforce these constraints:
+    # - Validate all paths are within allowed_paths before operations
+    # - Use Path.resolve() to canonicalize paths and prevent ../ attacks
+    # - Check symlinks don't point outside allowed paths (TOCTOU mitigation)
+    # - Reject absolute paths that escape the workspace
+    allowed_paths:
+      - "${WORKSPACE_ROOT}"
+    # -------------------------------------------------------------------------
+    # FILE SIZE LIMITS
+    # -------------------------------------------------------------------------
+    # Maximum file size for read/write operations (10 MB default).
+    # Prevents memory exhaustion attacks and limits blast radius.
+    max_file_size_bytes: 10485760
+    # -------------------------------------------------------------------------
+    # CONFIGURATION REQUIREMENTS
+    # -------------------------------------------------------------------------
+    # Documents required environment variables and initialization behavior.
+    configuration_requirements:
+      environment_variables:
+        WORKSPACE_ROOT:
+          required: true
+          description: >
+            Base directory for all filesystem operations. All paths are validated to be within this directory tree.
+
+          # CRITICAL: Handler MUST fail initialization if not set.
+          # This prevents accidental access to system files when misconfigured.
+          # Do NOT fall back to "/" or "." as this would expose the entire
+          # filesystem or current working directory.
+          missing_behavior: fail_initialization
+          validation:
+            - must_be_absolute_path
+            - must_exist
+            - must_be_directory
+      # Handler initialization MUST verify all required env vars before
+      # accepting any requests. Fail-fast prevents security misconfigurations.
+      initialization_policy: fail_fast_on_missing_config
+    # -------------------------------------------------------------------------
+    # FILE PERMISSION HANDLING
+    # -------------------------------------------------------------------------
+    # Strategy for handling file permissions during create/write operations.
+    file_permissions:
+      # Default permissions for newly created files (octal notation).
+      # 0o644 = owner read/write, group/other read-only.
+      default_file_mode: "0644"
+      # Default permissions for newly created directories.
+      # 0o755 = owner full access, group/other read/execute.
+      default_directory_mode: "0755"
+      # Whether to preserve existing permissions on overwrite.
+      # true = keep existing permissions, false = apply defaults.
+      preserve_on_overwrite: true
+      # SECURITY: Handler runs with process permissions. It cannot grant
+      # permissions beyond what the process user has. Operations that would
+      # require elevated privileges MUST fail with PermissionError.
+      # Do NOT attempt to use sudo or privilege escalation.
+      privilege_escalation: forbidden
+    # -------------------------------------------------------------------------
+    # RATE LIMITING
+    # -------------------------------------------------------------------------
+    # Rate limiting strategy for filesystem operations.
+    rate_limiting:
+      # NOTE: Rate limiting is DEFERRED to the orchestration layer.
+      # Rationale: The handler is a low-level effect that processes one
+      # request at a time (serialized concurrency). Rate limiting is more
+      # effectively implemented at:
+      # - API gateway level (request rate per client)
+      # - Orchestrator level (workflow-aware throttling)
+      # - Resource manager level (system-wide I/O limits)
+      #
+      # If handler-level rate limiting becomes necessary, implement using:
+      # - Token bucket algorithm for burst tolerance
+      # - Separate limits for read vs write operations
+      # - Correlation ID tracking to prevent single-client abuse
+      enabled: false
+      deferred_to: orchestration_layer
+      # Future implementation considerations:
+      future_considerations:
+        - per_operation_limits: "Different limits for read (high) vs write (low)"
+        - burst_allowance: "Token bucket with 10-request burst"
+        - backpressure_signal: "Return 429 with Retry-After header"
+    # -------------------------------------------------------------------------
+    # TOCTOU (Time-of-Check-Time-of-Use) MITIGATION
+    # -------------------------------------------------------------------------
+    # Strategies to mitigate race conditions between path validation and use.
+    toctou_mitigation:
+      # SECURITY: TOCTOU vulnerabilities occur when an attacker modifies the
+      # filesystem between our security check and the actual operation.
+      # Example attack: symlink is validated as safe, then replaced with a
+      # symlink to /etc/passwd before the read operation.
+      strategies:
+        # 1. Open file handles immediately after validation
+        # Use os.open() with O_NOFOLLOW to prevent symlink races, then
+        # perform operations on the file descriptor, not the path.
+        - strategy: use_file_descriptors
+          description: >
+            Open files immediately after path validation and operate on file descriptors rather than paths. This binds the operation to the specific inode, not the path.
+
+          implementation_note: >
+            Use os.open(path, os.O_RDONLY | os.O_NOFOLLOW) for reads. For writes, use O_CREAT | O_EXCL for new files to prevent symlink-based attacks.
+
+        # 2. Atomic operations where possible
+        # Use rename() for atomic file replacement, mkdir() with exist_ok=False
+        # to detect races.
+        - strategy: atomic_operations
+          description: >
+            Use atomic filesystem operations. Write to temp file then rename() for atomic replacement. Use O_EXCL flag to fail if file already exists (detects races).
+
+          implementation_note: >
+            tempfile.NamedTemporaryFile with delete=False, write content, then os.rename() to target. Rename is atomic on POSIX.
+
+        # 3. Re-validate after open
+        # After opening, verify the file descriptor points to expected location.
+        - strategy: post_open_validation
+          description: >
+            After opening a file handle, verify it still points to the expected location using os.fstat() and comparing device/inode.
+
+          implementation_note: >
+            Store (st_dev, st_ino) from os.stat() before open, compare with os.fstat(fd) after open. Mismatch indicates race.
+
+        # 4. Serialized concurrency (already configured)
+        # The serialized concurrency_policy in descriptor prevents parallel
+        # operations that could race with each other.
+        - strategy: serialized_operations
+          description: >
+            Handler uses serialized concurrency policy, preventing parallel handler invocations that could race.
+
+          note: Already configured in descriptor.concurrency_policy
+      # SECURITY: Symlink handling is critical for TOCTOU mitigation.
+      # Symlinks can be weaponized to escape allowed_paths.
+      symlink_policy:
+        # Whether to follow symlinks during path resolution.
+        # false = safer, prevents symlink-based escapes
+        # true = more flexible, but requires careful validation
+        follow_symlinks: false
+        # When follow_symlinks is true, validate that the resolved path
+        # is still within allowed_paths AFTER following all symlinks.
+        validate_resolved_path: true
+        # Maximum symlink depth to follow (prevents infinite loops).
+        max_symlink_depth: 10
+        # Reject symlinks that point outside allowed_paths.
+        reject_external_targets: true
+    # -------------------------------------------------------------------------
+    # INPUT VALIDATION
+    # -------------------------------------------------------------------------
+    # All inputs MUST be validated before use.
+    input_validation:
+      # Path validation requirements
+      path_validation:
+        - reject_null_bytes: true # Prevents null byte injection
+        - reject_control_chars: true # Prevents terminal injection
+        - max_path_length: 4096 # Prevents buffer overflow attacks
+        - max_filename_length: 255 # Filesystem limit
+        - reject_reserved_names: true # CON, PRN, etc. on Windows
+      # Content validation for write operations
+      content_validation:
+        - enforce_max_file_size: true # See max_file_size_bytes
+        - encoding_validation: optional # UTF-8 validation when applicable
+    # -------------------------------------------------------------------------
+    # AUDIT AND LOGGING
+    # -------------------------------------------------------------------------
+    # Security-relevant events that MUST be logged.
+    audit_logging:
+      # Events that MUST be logged for security audit trail
+      required_events:
+        - path_validation_failure # Attempted access outside allowed_paths
+        - symlink_escape_attempt # Symlink pointed outside allowed_paths
+        - permission_denied # OS-level permission failure
+        - file_size_exceeded # Attempted to read/write oversized file
+        - initialization_failure # Handler failed to initialize (missing env)
+      # Log level for security events
+      security_event_level: warning
+      # Include correlation_id in all logs for request tracing
+      include_correlation_id: true
+      # SECURITY: Never log file contents - only metadata
+      never_log:
+        - file_contents
+        - binary_data