python-statemachine 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

statemachine/io/evaluators.py

@@ -0,0 +1,303 @@
+"""Evaluation strategies for statechart datamodel expressions and scripts.
+
+An :class:`Evaluator` turns the raw expression/script strings carried by the
+neutral IR (:mod:`statemachine.io.model`) into callables, deciding *how* they are
+evaluated:
+
+- :class:`RestrictedEvaluator` (secure default): compiles expressions with the
+  AST-allowlist evaluator (:func:`statemachine.spec_parser.parse_expr`), which
+  cannot reach builtins, dunder attributes, or arbitrary calls. ``<script>`` and
+  raw-Python evaluation are rejected because they are arbitrary code.
+- :class:`PythonEvaluator` (opt-in, ``trusted=True``): preserves the legacy
+  behavior of evaluating expressions and scripts as arbitrary Python via
+  ``eval``/``exec``.
+
+The restricted evaluator validates the *structure* of an expression at compile
+time (a violation raises :class:`~statemachine.exceptions.InvalidDefinition`),
+but name resolution and value computation still happen at call time, so runtime
+errors (``NameError``, ``TypeError``) keep flowing to ``error.execution`` as
+before.
+
+The evaluator is also the trust gate for external resource references: an external
+``<data src>`` / ``<invoke src>`` reads a local file, so the restricted evaluator rejects
+it via :meth:`ensure_external_src_allowed` (the trusted one allows it).
+
+This module is format-neutral: it is shared by the SCXML, JSON and YAML readers.
+See the :mod:`statemachine.io.scxml` package docstring and the GHSA-v4jc-pm6r-3vj8
+(code execution) and GHSA-fj3w-533r-fvf6 (file disclosure) advisories for the rationale.
+"""
+
+import ast
+import html
+import re
+from collections.abc import Callable
+from inspect import isawaitable
+from typing import Any
+from typing import Protocol
+
+from ..dispatcher import callable_method
+from ..event import _event_data_kwargs
+from ..exceptions import InvalidDefinition
+from ..spec_parser import InState
+from ..spec_parser import parse_expr
+
+#: Attributes that must never be exposed to or overwritten by datamodel
+#: expressions (engine internals and SCXML system variables).
+protected_attrs = _event_data_kwargs | {"_sessionid", "_ioprocessors", "_name", "_event"}
+
+
+_COND_REPLACEMENTS = {
+    "true": "True",
+    "false": "False",
+    "null": "None",
+    "===": "==",
+    "!==": "!=",
+    "&&": "and",
+    "||": "or",
+}
+_COND_PATTERN = re.compile(r"\b(?:true|false|null)\b|===|!==|&&|\|\|")
+
+
+def normalize_cond(cond: str) -> str:
+    """Normalize a JavaScript-like condition to Python syntax.
+
+    Decodes XML entities (e.g. ``&lt;``) and maps ``true``/``false``/``null`` and
+    the ``===``/``!==``/``&&``/``||`` operators to their Python equivalents. This
+    is primarily an SCXML (ECMAScript datamodel) concern; for Python-style
+    expressions (JSON/YAML) it is effectively a no-op.
+    """
+    cond = html.unescape(cond)
+    return _COND_PATTERN.sub(lambda match: _COND_REPLACEMENTS[match.group(0)], cond)
+
+
+def _resolvable_model_attr(name: str, model) -> bool:
+    """The secure boundary for resolving a bare name off the model.
+
+    Engine-protected names (``machine``, ``event``, system variables, …) and any
+    private/dunder name (leading underscore) never resolve off the model, mirroring the
+    dotted-access guard in :func:`statemachine.spec_parser.build_attribute`. System
+    variables stay reachable because they are provided via the call kwargs, which are
+    consulted before this. This keeps a semi-trusted document from reading the model's
+    internals (``_secret``) or walking the object graph (``__class__``).
+    """
+    return name not in protected_attrs and not name.startswith("_") and hasattr(model, name)
+
+
+def variable_hook(name: str) -> Callable:
+    """Resolve a datamodel name at call time.
+
+    Looks the name up in the call kwargs first (SCXML system variables such as
+    ``_event``, ``_name``), then falls back to a (non-protected, non-private) attribute of
+    ``machine.model``. Names in :data:`~statemachine.event._event_data_kwargs` (``machine``,
+    ``model``, ``event``, ``transition``, ...) are the live engine-capability objects; they
+    are **withheld** from the kwargs lookup so an untrusted expression cannot obtain the
+    engine and pivot through it onto shared classes (GHSA-v3qq-3xvg-m77g). The ``_``-prefixed
+    system variables are not engine objects and stay resolvable.
+    """
+
+    def resolver(*args, **kwargs):
+        if name not in _event_data_kwargs and name in kwargs:
+            return kwargs[name]
+        model = kwargs["machine"].model
+        if _resolvable_model_attr(name, model):
+            return getattr(model, name)
+        raise NameError(f"name '{name}' is not defined")
+
+    resolver.__name__ = name
+    return resolver
+
+
+def cond_variable_hook(name: str) -> Callable:
+    """Resolve a name inside a guard, following the Python guard dialect.
+
+    Same lookup as :func:`variable_hook`, but a referenced **method** is *called*
+    (with dependency injection), while a property or plain attribute is *read*.
+    This keeps native ``cond``/``unless`` at parity with class-defined guards (see
+    ``docs/guards.md``): a name can be a property, an attribute or a method.
+    """
+
+    def resolver(*args, **kwargs):
+        if name not in _event_data_kwargs and name in kwargs:
+            return kwargs[name]
+        model = kwargs["machine"].model
+        if _resolvable_model_attr(name, model):
+            value = getattr(model, name)
+            if callable(value):
+                return callable_method(value)(*args, **kwargs)
+            return value
+        raise NameError(f"name '{name}' is not defined")
+
+    resolver.__name__ = name
+    return resolver
+
+
+def _eval(expr: str, **kwargs) -> Any:
+    """Evaluate an expression as arbitrary Python (``trusted=True`` path only).
+
+    .. warning::
+
+        Calls the built-in :func:`eval` with no sandboxing. Only reachable when
+        the document is loaded with ``trusted=True``.
+    """
+    if "machine" in kwargs:
+        kwargs.update(
+            **{
+                k: v
+                for k, v in kwargs["machine"].model.__dict__.items()
+                if k not in protected_attrs
+            }
+        )
+        kwargs["In"] = InState(kwargs["machine"])
+    return eval(expr, {}, kwargs)
+
+
+class Evaluator(Protocol):
+    """Port: turns expression/script strings into callables.
+
+    This is the contract consumers (the processors, action compilers) depend on. They
+    never name a concrete implementation; wiring goes through :func:`evaluator_for`.
+    """
+
+    def compile_value(self, expr: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a value expression (``<assign>``, ``<send>``, ``<data>``, ...)."""
+        ...
+
+    def compile_bool(self, expr: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a boolean guard expression (``cond``)."""
+        ...
+
+    def compile_script(self, content: str) -> Callable:  # pragma: no cover - structural Protocol
+        """Compile a ``<script>`` body into a callable side effect."""
+        ...
+
+    def eval_literal(self, content: str) -> Any:  # pragma: no cover - structural Protocol
+        """Evaluate inline ``<content>`` as a literal, falling back to the raw string."""
+        ...
+
+    def ensure_external_src_allowed(  # pragma: no cover - structural Protocol
+        self, descriptor: str
+    ) -> None:
+        """Guard external resource references (``<data src>`` / ``<invoke src>``).
+
+        Reading a local file named by an untrusted document is a confidentiality risk, so
+        it is gated on the trust level just like ``<script>``. ``descriptor`` names the
+        offending element for the error message.
+        """
+        ...
+
+
+class RestrictedEvaluator:
+    """Secure default: AST-allowlist evaluation, no ``eval``/``exec``.
+
+    ``<script>`` and any expression outside the supported subset (method calls,
+    dunder attribute access, lambdas, comprehensions, ...) are rejected at
+    compile time with :class:`~statemachine.exceptions.InvalidDefinition`.
+    """
+
+    def compile_value(self, expr: str) -> Callable:
+        return self._compile(expr, variable_hook)
+
+    def compile_bool(self, expr: str) -> Callable:
+        # Guards resolve names with the Python dialect (methods are called); the
+        # result is coerced to bool, awaiting it first when a coroutine (an async
+        # guard method) flows through, so the async engine works too.
+        value_fn = self._compile(normalize_cond(expr), cond_variable_hook)
+
+        def cond(*args, **kwargs):
+            result = value_fn(*args, **kwargs)
+            if isawaitable(result):
+
+                async def _coerce():
+                    return bool(await result)
+
+                return _coerce()
+            return bool(result)
+
+        return cond
+
+    def compile_script(self, content: str) -> Callable:
+        raise InvalidDefinition(
+            "<script> executes arbitrary code and is disabled by default. Pass "
+            "trusted=True to enable it, and only for trusted sources."
+        )
+
+    def eval_literal(self, content: str) -> Any:
+        try:
+            return ast.literal_eval(content)
+        except (ValueError, SyntaxError):
+            return content
+
+    def ensure_external_src_allowed(self, descriptor: str) -> None:
+        raise InvalidDefinition(
+            f"{descriptor} loads a local file and is disabled by default. Pass "
+            "trusted=True to enable it, and only for trusted sources."
+        )
+
+    @staticmethod
+    def _compile(expr: str, hook: Callable) -> Callable:
+        try:
+            return parse_expr(expr, hook)
+        except (ValueError, SyntaxError) as exc:
+            raise InvalidDefinition(
+                f"Expression {expr!r} is not allowed by the restricted "
+                f"datamodel ({exc}). Pass trusted=True to evaluate it as "
+                f"Python, and only for trusted sources."
+            ) from exc
+
+
+class PythonEvaluator:
+    """Opt-in (``trusted=True``): evaluate expressions and scripts as Python.
+
+    Preserves the legacy ``eval``/``exec`` behavior, including error timing
+    (syntax/name errors surface at call time and become ``error.execution``).
+    """
+
+    def compile_value(self, expr: str) -> Callable:
+        def value(*args, **kwargs):
+            return _eval(expr, **kwargs)
+
+        return value
+
+    def compile_bool(self, expr: str) -> Callable:
+        # Intentionally uses ``eval`` (not ``parse_expr``): the whole point of the
+        # trusted evaluator is to accept guards the restricted AST allowlist rejects —
+        # method/function calls, builtins, etc. (e.g. SCXML conformance conds like
+        # ``_event.data.get('x') == 1`` or ``hasattr(_event, 'name')``). Routing this
+        # through ``parse_expr`` would make trusted mode no more capable than the
+        # restricted one for guards and would break those documents.
+        normalized = normalize_cond(expr)
+
+        def cond(*args, **kwargs):
+            return _eval(normalized, **kwargs)
+
+        return cond
+
+    def compile_script(self, content: str) -> Callable:
+        def script(*args, **kwargs):
+            machine = kwargs["machine"]
+            local_vars = {**machine.model.__dict__}
+            exec(content, {}, local_vars)
+            for var_name, value in local_vars.items():
+                setattr(machine.model, var_name, value)
+
+        return script
+
+    def eval_literal(self, content: str) -> Any:
+        try:
+            return eval(content, {}, {})
+        except (NameError, SyntaxError, TypeError):
+            return content
+
+    def ensure_external_src_allowed(self, descriptor: str) -> None:
+        return None
+
+
+def evaluator_for(trusted: bool = False) -> Evaluator:
+    """Return the evaluation strategy for the given trust level (the wiring point).
+
+    This is the single place that maps the public ``trusted`` flag to a concrete
+    adapter, so no other module needs to import :class:`RestrictedEvaluator` or
+    :class:`PythonEvaluator`. The default (``trusted=False``) is the secure restricted
+    evaluator, so callers that omit the argument get the safe behaviour.
+    """
+    return PythonEvaluator() if trusted else RestrictedEvaluator()

statemachine/io/interpreter.py

@@ -0,0 +1,128 @@
+"""Format-neutral runtime that turns statechart definitions into running machines.
+
+The :class:`Interpreter` is the execution-model runtime, independent of input syntax. It
+owns a :class:`~statemachine.io.builder.DefinitionBuilder` (compilation), keeps the
+registry of compiled classes (``scs``, needed for ``<invoke>``), manages per-machine
+sessions, injects the system variables (``_event``/``_sessionid``/``_name``/
+``_ioprocessors``) on every event, coordinates invoke, and instantiates the root machine.
+
+It is parameterized by two ports: a :class:`~statemachine.io.ports.FormatReader` (so invoke
+can compile children in the same format) and an
+:class:`~statemachine.io.evaluators.Evaluator` (secure by default). SCXML is just one
+reader; YAML/JSON get the very same runtime behavior.
+"""
+
+import os
+from typing import Any
+
+from ..exceptions import InvalidDefinition
+from ..statemachine import StateChart
+from .builder import DefinitionBuilder
+from .class_factory import create_machine_class_from_definition
+from .evaluators import Evaluator
+from .invoke import Invoker
+from .model import InvokeDefinition
+from .model import StateMachineDefinition
+from .system_variables import IOProcessor
+from .system_variables import SessionData
+from .system_variables import build_system_variables
+from .system_variables import create_invoke_init_callable
+
+
+class Interpreter:
+    """Runtime that compiles and hosts statecharts from any format.
+
+    Args:
+        reader: the format reader, used to compile invoked children in the same format.
+        evaluator: the evaluation strategy for guards and executable content.
+    """
+
+    def __init__(self, *, reader, evaluator: Evaluator):
+        self.reader = reader
+        self._evaluator = evaluator
+        self._builder = DefinitionBuilder(evaluator=evaluator, hooks=self)
+        self.scs: "dict[str, type[StateChart]]" = {}
+        self.sessions: dict[str, SessionData] = {}
+
+    def process_definition(
+        self, definition: StateMachineDefinition, location: str, is_invoked: bool = False
+    ):
+        kwargs = self._builder.build_class_kwargs(definition, is_invoked=is_invoked)
+        self._add(location, kwargs)
+
+    def start(self, **kwargs):
+        self.root_cls = next(iter(self.scs.values()))
+        self.root = self.root_cls(**kwargs)
+        return self.root
+
+    # -- RuntimeHooks (called back by the DefinitionBuilder) -----------------------
+
+    def initial_enter_prefix(self, is_invoked: bool) -> list:
+        # Invoked children store _invoke_session/_invoke_params before any other callback.
+        if is_invoked:
+            return [create_invoke_init_callable()]
+        return []
+
+    def definition_kwargs(self, definition) -> "dict[str, Any]":
+        """Extra keyword arguments passed to ``create_machine_class_from_definition``.
+
+        The three structural ``validate_*`` checks are turned **off** for loaded
+        statecharts: declarative documents legitimately express configurations these
+        checks would reject (states reached only through parallel regions or eventless
+        paths, intentional trap/error states). The trade-off is that genuine structural
+        inconsistencies are not caught at load time; see the validations reference and
+        ``docs/io``. ``prepare_event`` injects the system variables for every format.
+        """
+        return {
+            "validate_disconnected_states": False,
+            "validate_trap_states": False,
+            "validate_final_reachability": False,
+            "start_configuration_values": list(definition.initial_states),
+            "prepare_event": self._prepare_event,
+        }
+
+    def make_invoker(self, invoke_def: InvokeDefinition) -> Invoker:
+        return Invoker(
+            definition=invoke_def,
+            base_dir=os.getcwd(),
+            register_child=self._register_child,
+            evaluator=self._evaluator,
+        )
+
+    # -- Runtime services ----------------------------------------------------------
+
+    def _prepare_event(self, *args, event, **kwargs):
+        machine = kwargs["machine"]
+        session_data = self._get_session(machine)
+        return build_system_variables(machine, session_data, event, kwargs["event_data"])
+
+    def _get_session(self, machine) -> SessionData:
+        if machine.name not in self.sessions:
+            self.sessions[machine.name] = SessionData(
+                processor=IOProcessor(self, machine=machine), machine=machine
+            )
+        return self.sessions[machine.name]
+
+    def _register_child(self, content, child_name: str) -> type:
+        """Compile and register a child statechart.
+
+        ``content`` is either source text (parsed via this interpreter's reader, so the
+        child is in the same format) or an already-parsed
+        :class:`~statemachine.io.model.StateMachineDefinition` (native inline child).
+        """
+        if isinstance(content, StateMachineDefinition):
+            definition = content
+        else:
+            definition = self.reader.read(content)
+        self.process_definition(definition, location=child_name, is_invoked=True)
+        return self.scs[child_name]
+
+    def _add(self, location: str, definition: dict[str, Any]):
+        try:
+            sc_class = create_machine_class_from_definition(location, **definition)
+            self.scs[location] = sc_class
+            return sc_class
+        except Exception as e:  # pragma: no cover
+            raise InvalidDefinition(
+                f"Failed to create state machine class: {e} from definition: {definition}"
+            ) from e