python-statemachine 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

statemachine/factory.py

@@ -5,6 +5,8 @@ from . import registry
 from .callbacks import CallbackGroup
 from .callbacks import CallbackPriority
 from .callbacks import CallbackSpecList
+from .callbacks import SpecReference
+from .callbacks import is_unbounded_reference
 from .event import Event
 from .event import _expand_event_id
 from .exceptions import InvalidDefinition
@@ -13,12 +15,25 @@ from .graph import iterate_states
 from .graph import iterate_states_and_transitions
 from .graph import states_without_path_to_final_states
 from .i18n import _
+from .spec_parser import names_in_boolean_expr
 from .state import State
 from .states import States
 from .transition import Transition
 from .transition_list import TransitionList
 
 
+def _same_callable(func: Any, other: Any) -> bool:
+    return type(func) is type(other) and func == other
+
+
+def _can_store_apart(existing: Any, owners: list[tuple[State, Any]]) -> bool:
+    """Only callbacks held by object can move to a key of their own: a name is still
+    reachable through ``self.<name>``, so it must not lose a plain method or attribute."""
+    return all(is_unbounded_reference(func) for _, func in owners) and (
+        existing is None or isinstance(existing, Event) or is_unbounded_reference(existing)
+    )
+
+
 class StateMachineMetaclass(type):
     "Metaclass for constructing StateMachine classes"
 
@@ -51,7 +66,7 @@ class StateMachineMetaclass(type):
         cls._abstract = True
         cls._events: dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
         cls._protected_attrs: set = set()
-        cls._events_to_update: dict[Event, Event | None] = {}
+        cls._events_to_update: dict[Event, list[Event]] = {}
         cls._specs = CallbackSpecList()
         cls.prepare = cls._specs.grouper(CallbackGroup.PREPARE).add(
             "prepare_event", priority=CallbackPriority.GENERIC, is_convention=True
@@ -59,7 +74,6 @@ class StateMachineMetaclass(type):
         cls.add_inherited(bases)
         cls.add_from_attributes(attrs)
         cls._collect_class_listeners(attrs, bases)
-        cls._unpack_builders_callbacks()
         cls._update_event_references()
 
         if not cls.states:
@@ -88,6 +102,7 @@ class StateMachineMetaclass(type):
 
         cls._check()
         cls._setup()
+        cls._unpack_builders_callbacks(attrs)
         cls._expand_docstring()
 
     _STATECHART_RE = re.compile(r"\{statechart:(\w+)\}")
@@ -163,14 +178,96 @@ class StateMachineMetaclass(type):
             if not any(t for t in parent.transitions if t.initial and t.target == state):
                 parent.to(state, initial=True)  # pragma: no cover
 
-    def _unpack_builders_callbacks(cls):
-        callbacks = {}
+    def _unpack_builders_callbacks(cls, attrs: dict[str, Any]):
+        names_resolved_by_name = cls._names_resolved_by_name()
+        relocated: dict[Any, str] = {}
+        for attr_name, owners in cls._nested_callbacks().items():
+            existing = cls.__dict__.get(attr_name)
+            owners = [(s, f) for s, f in owners if not _same_callable(f, existing)]
+            if not owners:
+                continue
+            if existing is None and len(owners) == 1:
+                setattr(cls, attr_name, owners[0][1])
+                continue
+            if attr_name in names_resolved_by_name or not _can_store_apart(existing, owners):
+                cls._raise_callback_collision(attr_name, existing, owners, attrs)
+            for state, func in owners:
+                relocated[func] = f"{state.id}:{attr_name}"
+                setattr(cls, relocated[func], func)
+        own_states = [value for value in attrs.values() if isinstance(value, State)]
+        cls._update_lookup_names(relocated, own_states)
+
+    def _nested_callbacks(cls) -> dict[str, list[tuple[State, Any]]]:
+        """Distinct callables declared under each name, with the state body declaring them."""
+        claims: dict[str, list[tuple[State, Any]]] = {}
         for state in iterate_states(cls.states):
             if state._callbacks:
-                callbacks.update(state._callbacks)
-                del state._callbacks
-        for key, value in callbacks.items():
-            setattr(cls, key, value)
+                for attr_name, func in state._callbacks.items():
+                    owners = claims.setdefault(attr_name, [])
+                    if not any(_same_callable(func, other) for _, other in owners):
+                        owners.append((state, func))
+                state._callbacks = None
+        return claims
+
+    def _update_lookup_names(cls, relocated: dict[Any, str], own_states: list[State]):
+        """Inherited states share their specs with the base class, which must keep its own."""
+        if not relocated:
+            return
+        for visited in iterate_states_and_transitions(own_states):
+            for spec in visited._specs:
+                if spec.reference is SpecReference.CALLABLE and spec.func in relocated:
+                    spec.lookup_name = relocated[spec.func]
+
+    def _all_specs(cls):
+        yield cls._specs
+        for visited in iterate_states_and_transitions(cls.states):
+            yield visited._specs
+
+    def _names_resolved_by_name(cls) -> set[str]:
+        names: set[str] = set()
+        for specs in cls._all_specs():
+            for spec in specs:
+                if spec.may_contain_boolean_expression:
+                    names.update(names_in_boolean_expr(spec.attr_name))
+                elif spec.reference is SpecReference.NAME:
+                    names.add(spec.attr_name)
+        return names
+
+    def _raise_callback_collision(
+        cls,
+        attr_name: str,
+        existing: Any,
+        owners: list[tuple[State, Any]],
+        attrs: dict[str, Any],
+    ):
+        class_body_names = set(attrs)
+        class_body_names.update(
+            value.attr_name for value in attrs.values() if getattr(value, "attr_name", None)
+        )
+        state, func = owners[0]
+        if existing is None:
+            conflict = _("is declared in both the '{}' and the '{}' state bodies").format(
+                state.id, owners[1][0].id
+            )
+        elif isinstance(existing, Event):
+            conflict = _("in the '{}' state body clashes with the event '{}'").format(
+                state.id, existing.id
+            )
+        elif attr_name in class_body_names:
+            conflict = _("is declared in both the '{}' state body and the '{}' class body").format(
+                state.id, cls.__name__
+            )
+        else:
+            conflict = _("in the '{}' state body clashes with the '{}' attribute of '{}'").format(
+                state.id, attr_name, cls.__name__
+            )
+        name = func.__name__ if getattr(func, "is_event", False) else attr_name
+        raise InvalidDefinition(
+            _(
+                "Callback '{}' {}. Nested state bodies share the class namespace. "
+                "Rename one of them."
+            ).format(name, conflict)
+        )
 
     def _check(cls):
         has_states = bool(cls.states)
@@ -305,21 +402,21 @@ class StateMachineMetaclass(type):
             if isinstance(value, State):
                 cls.add_state(key, value)
             elif isinstance(value, (Transition, TransitionList)):
-                event_id = _expand_event_id(key)
-                cls.add_event(event=Event(transitions=value, id=event_id))
+                for event_id in _expand_event_id(key):
+                    cls.add_event(event=Event(transitions=value, id=event_id))
             elif isinstance(value, (Event,)):
-                if value._has_real_id:
-                    event_id = value.id
-                else:
-                    event_id = _expand_event_id(key)
-                new_event = Event(
-                    transitions=value._transitions,
-                    id=event_id,
-                    name=value.name,
-                )
-                cls.add_event(event=new_event, old_event=value)
+                event_ids = [value.id] if value._has_real_id else _expand_event_id(key)
+                for event_id in event_ids:
+                    new_event = Event(
+                        transitions=value._transitions,
+                        id=event_id,
+                        name=value.name,
+                        delay=value.delay,
+                        internal=value.internal,
+                    )
+                    cls.add_event(event=new_event, old_event=value)
                 # Ensure the event is accessible by the Python attribute name
-                if event_id != key:
+                if key not in event_ids:
                     setattr(cls, key, new_event)
             elif getattr(value, "attr_name", None):
                 cls._add_unbounded_callback(key, value)
@@ -334,7 +431,8 @@ class StateMachineMetaclass(type):
         # machinery that is stored at ``func.attr_name``
         setattr(cls, func.attr_name, func)
         if func.is_event:
-            cls.add_event(event=Event(func._transitions, id=attr_name))
+            for event_id in _expand_event_id(attr_name):
+                cls.add_event(event=Event(func._transitions, id=event_id))
 
     def add_state(cls, id, state: State):
         state._set_id(id)
@@ -357,8 +455,7 @@ class StateMachineMetaclass(type):
         old_event: "Event | None" = None,
     ):
         if not event._has_real_id:
-            if event not in cls._events_to_update:
-                cls._events_to_update[event] = None
+            cls._events_to_update.setdefault(event, [])
             return
 
         transitions = event._transitions
@@ -370,20 +467,20 @@ class StateMachineMetaclass(type):
             setattr(cls, event.id, event)
 
         if old_event is not None:
-            cls._events_to_update[old_event] = event
+            cls._events_to_update.setdefault(old_event, []).append(event)
 
         return cls._events[event]
 
     def _update_event_references(cls):
-        for old_event, new_event in cls._events_to_update.items():
+        for old_event, new_events in cls._events_to_update.items():
             for state in cls.states:
                 for transition in state.transitions:
-                    if transition._events.match(old_event):
-                        if new_event is None:
+                    if old_event in transition._events:
+                        if not new_events:
                             raise InvalidDefinition(
                                 _("An event in the '{}' has no id.").format(transition)
                             )
-                        transition.events._replace(old_event, new_event)
+                        transition.events._replace(old_event, new_events)
 
         cls._events_to_update = {}
 

statemachine/io/__init__.py

@@ -11,19 +11,26 @@ whether it was authored in SCXML, JSON or YAML.
 Security
 --------
 
-Loading a document compiles its guards, datamodel expressions and executable content into
-callables. Because a document may come from a semi-trusted source, loading is **secure by
-default** (``trusted=False``): expressions are evaluated by a **restricted AST-whitelist
-evaluator** that cannot reach builtins, dunder attributes, or arbitrary calls, and
-``<script>`` / ``script`` (arbitrary code) is rejected. This mirrors ``yaml.safe_load`` and
-keeps loading from turning into arbitrary code execution.
+A statechart is an *executable document*, not inert data, so loading one is closer to importing
+code than to parsing JSON. Because a document may come from a semi-trusted source, loading is
+**secure by default** (``trusted=False``): expressions are evaluated by a **restricted
+AST-allowlist evaluator** that cannot reach builtins, dunder attributes or arbitrary calls;
+``<script>`` / ``script`` (arbitrary code) is rejected; external resource references
+(``<data src>`` / ``<invoke src>``, which read local files) are rejected; write targets are
+confined to public model attributes; and ``**``/``*`` are magnitude-capped.
 
-Passing ``trusted=True`` restores full ``eval``/``exec`` evaluation and enables ``script``.
-In that mode a document is equivalent to executable Python (much like :mod:`pickle`), so
-**only load ``trusted`` documents from sources you control** (hand-authored documents, the
-output of your own tooling, the W3C conformance suite).
+Passing ``trusted=True`` restores full ``eval``/``exec`` evaluation, enables ``script`` and
+allows external ``src`` references. In that mode a document is equivalent to executable Python
+(much like :mod:`pickle`), so **only load ``trusted`` documents from sources you control**
+(hand-authored documents, the output of your own tooling, the W3C conformance suite).
 
-See the GHSA-v4jc-pm6r-3vj8 advisory for details.
+The intended use of ``trusted=False`` is your own dynamic definitions (a no-code editor, your
+tooling, config you control); it is *hardening*, not a sandbox. It guarantees confidentiality
+and integrity, not availability: a *running* machine can still exhaust resources (eventless
+loops, large ``<foreach>``, recursive ``<invoke>``), so run genuinely untrusted documents under
+your own timeout/resource limits or OS-level isolation. See the GHSA-v4jc-pm6r-3vj8,
+GHSA-fj3w-533r-fvf6, GHSA-v3qq-3xvg-m77g, GHSA-4857-ggqc-p3jc and GHSA-r8gj-366q-cgvj advisories,
+and ``docs/io/security.md``, for details.
 """
 
 from .class_factory import ActionProtocol

statemachine/io/actions.py

@@ -8,13 +8,16 @@ is format-neutral: it is shared by the SCXML, JSON and YAML readers.
 
 import logging
 import re
+import types
 from collections.abc import Callable
 from itertools import chain
 from typing import Any
+from urllib.parse import urlparse
 from uuid import uuid4
 
 from ..event import BoundEvent
 from ..event import Event
+from ..event import raise_delayed_internal
 from ..statemachine import StateChart
 from .evaluators import Evaluator
 from .evaluators import protected_attrs
@@ -37,6 +40,80 @@ logger = logging.getLogger(__name__)
 _debug = logger.debug if logger.isEnabledFor(logging.DEBUG) else lambda *a, **k: None
 
 
+def _ensure_writable_target(name: str, descriptor: str) -> None:
+    """Reject a document-controlled write target that isn't a plain public attribute.
+
+    Executable content chooses the *name* it writes to: ``<assign location>`` (each dotted
+    segment), ``<foreach item>``/``index``, ``<data id>`` and ``<send>``/``<invoke>``
+    ``idlocation``. A private, dunder or engine-protected name lets an untrusted document
+    reach internals or, by traversing ``__class__``, corrupt the shared model class
+    process-wide (GHSA-v3qq-3xvg-m77g, GHSA-4857-ggqc-p3jc). Only a valid, public (no
+    leading ``_``), non-protected identifier may be written. Raised as ``ValueError`` so the
+    engine routes it to ``error.execution`` like any other executable-content failure.
+    """
+    if not name.isidentifier() or name.startswith("_") or name in protected_attrs:
+        raise ValueError(
+            f"{descriptor} cannot write to a private, dunder or protected name: {name!r}"
+        )
+
+
+def _reject_type_or_module(obj: Any, descriptor: str) -> None:
+    """Reject traversing through or writing onto a class or module.
+
+    A class (``isinstance(obj, type)``) or module is shared process-wide, so a ``setattr``
+    on it (or a hop through it) corrupts every user of that class/module, not just this
+    machine. Even if an untrusted expression manages to obtain such an object as a value
+    (e.g. via a leaked engine capability), the write target guard blocks the mutation
+    (GHSA-v3qq-3xvg-m77g). Plain data instances are unaffected. Raised as ``ValueError`` so
+    the engine routes it to ``error.execution``.
+    """
+    if isinstance(obj, type) or isinstance(obj, types.ModuleType):
+        raise ValueError(f"{descriptor} cannot traverse or write onto a class or module: {obj!r}")
+
+
+def _reject_engine_capability(obj: Any, descriptor: str) -> None:
+    """Reject traversing through or writing onto a live engine-capability object.
+
+    Beyond classes and modules (:func:`_reject_type_or_module`), the engine's own runtime
+    objects are shared, mutable capabilities: the machine
+    (:class:`~statemachine.statemachine.StateChart`, and thus ``StateMachine``), the io
+    :class:`~statemachine.io.interpreter.Interpreter`, the core
+    :class:`~statemachine.state.State` / :class:`~statemachine.transition.Transition` /
+    :class:`~statemachine.event.Event`, the system-variable facades
+    (:class:`~statemachine.io.system_variables.EventDataWrapper` /
+    :class:`~statemachine.io.system_variables.IOProcessor`) and the event carriers
+    (:class:`~statemachine.event_data.EventData` / :class:`~statemachine.event_data.TriggerData`).
+    A ``setattr`` on any of them (or a hop through one) mutates state shared across sibling
+    machine instances of the same loaded class. Even if some public alias ever leaks such
+    an object as a value, this blocks pivoting the write onto a shared object
+    (GHSA-v3qq-3xvg-m77g). The datamodel container (:class:`~statemachine.model.Model`, the
+    legitimate ``machine.model`` root) and plain data (dict/list/str/int/ordinary app model
+    instances) are unaffected. Lazy imports keep this off the module import cycle. Raised as
+    ``ValueError`` so the engine routes it to ``error.execution``.
+    """
+    from ..event_data import EventData
+    from ..event_data import TriggerData
+    from ..state import State
+    from ..transition import Transition
+    from .interpreter import Interpreter
+    from .system_variables import EventDataWrapper
+    from .system_variables import IOProcessor
+
+    engine_types = (
+        StateChart,
+        Interpreter,
+        State,
+        Transition,
+        Event,
+        EventDataWrapper,
+        IOProcessor,
+        EventData,
+        TriggerData,
+    )
+    if isinstance(obj, engine_types):
+        raise ValueError(f"{descriptor} cannot traverse or write onto an engine object: {obj!r}")
+
+
 class ParseTime:
     pattern = re.compile(r"(\d+(?:\.\d+)?|\.\d+)(s|ms)")
     """CSS2 time literal: a number (``5``, ``1.5``, ``.5``) followed by ``s`` or ``ms``."""
@@ -164,20 +241,30 @@ class Assign(CallableAction):
             value = self._expr(*args, **kwargs)  # type: ignore[misc]
 
         *path, attr = self.action.location.split(".")
+        descriptor = f"<assign> 'location' ({self.action.location!r})"
         obj = machine.model
+        # Validate every hop (initial, intermediate and final): traversing a private/dunder
+        # object (e.g. ``__class__``) or writing a protected name is how an untrusted document
+        # escapes the datamodel, validating only the final segment left that open. A class or
+        # module (``_reject_type_or_module``) and a live engine-capability instance
+        # (``_reject_engine_capability``: machine/interpreter/State/Transition/Event and the
+        # system-variable facades) are additionally rejected as a hop or write target, so even
+        # a value that leaked such an object cannot be pivoted onto shared state
+        # (GHSA-v3qq-3xvg-m77g).
         for p in path:
+            _ensure_writable_target(p, descriptor)
+            _reject_type_or_module(obj, descriptor)
+            _reject_engine_capability(obj, descriptor)
             obj = getattr(obj, p)
 
-        if not attr.isidentifier() or not (hasattr(obj, attr) or attr in kwargs):
+        _ensure_writable_target(attr, descriptor)
+        _reject_type_or_module(obj, descriptor)
+        _reject_engine_capability(obj, descriptor)
+        if not (hasattr(obj, attr) or attr in kwargs):
             raise ValueError(
-                f"<assign> 'location' must be a valid Python attribute name and must be declared, "
+                f"<assign> 'location' must be declared before assignment, "
                 f"got: {self.action.location}"
             )
-        if attr in protected_attrs:
-            raise ValueError(
-                f"<assign> 'location' cannot assign to a protected attribute: "
-                f"{self.action.location}"
-            )
         setattr(obj, attr, value)
         _debug("Assign: %s = %r", self.action.location, value)
 
@@ -242,10 +329,9 @@ def create_foreach_action_callable(action: ForeachAction, evaluator: Evaluator)
         except Exception as e:
             raise ValueError(f"Error evaluating <foreach> 'array' expression: {e}") from e
 
-        if not action.item.isidentifier():
-            raise ValueError(
-                f"<foreach> 'item' must be a valid Python attribute name, got: {action.item}"
-            )
+        _ensure_writable_target(action.item, "<foreach> 'item'")
+        if action.index:
+            _ensure_writable_target(action.index, "<foreach> 'index'")
         for index, item in enumerate(array):
             # Assign the item and optionally the index
             setattr(machine.model, action.item, item)
@@ -315,6 +401,9 @@ def create_send_action_callable(  # noqa: C901
 ) -> Callable:
     content: Any = ()
     _valid_targets = (None, "#_internal", "internal", "#_parent", "parent")
+    internal = action.target in ("#_internal", "internal")
+    if internal and (action.delay or action.delayexpr):
+        raise_delayed_internal(action.event or action.eventexpr or "")
     if action.content:
         content = (evaluator.eval_literal(action.content),)
     delay_expr = (
@@ -348,12 +437,11 @@ def create_send_action_callable(  # noqa: C901
             _send_to_parent(action, evaluator, **kwargs)
             return
 
-        internal = target in ("#_internal", "internal")
-
         send_id = None
         if action.id:
             send_id = action.id
         elif action.idlocation:
+            _ensure_writable_target(action.idlocation, "<send> 'idlocation'")
             send_id = uuid4().hex
             setattr(machine.model, action.idlocation, send_id)
 
@@ -408,12 +496,33 @@ def create_script_action_callable(action: ScriptAction, evaluator: Evaluator) ->
     return script_action
 
 
+def _resolve_data_src(action: DataItem, evaluator: Evaluator) -> "str | None":
+    """Read a ``<data src="file:…">`` reference at compile time, gated on trust.
+
+    Only the ``file`` scheme is resolved (mirroring the SCXML reader's historical
+    behaviour). Reading a local file named by an untrusted document is a confidentiality
+    risk, so the restricted evaluator rejects it; ``trusted=True`` reads it as before.
+    Runs inside the document's base directory (``loader._build`` ``_chdir``), so relative
+    paths resolve against the document.
+    """
+    if action.src is None:
+        return None
+    src_parsed = urlparse(action.src)
+    if src_parsed.scheme != "file":
+        return None
+    evaluator.ensure_external_src_allowed(f"<data id={action.id!r} src=...>")
+    with open(src_parsed.path) as f:
+        return f.read()
+
+
 def _create_dataitem_callable(action: DataItem, evaluator: Evaluator) -> Callable:
+    content = action.content if action.content else _resolve_data_src(action, evaluator)
     expr_fn = evaluator.compile_value(action.expr) if action.expr else None
-    content_fn = evaluator.compile_value(action.content) if action.content else None
+    content_fn = evaluator.compile_value(content) if content else None
 
     def data_initializer(**kwargs):
         machine: StateChart = kwargs["machine"]
+        _ensure_writable_target(action.id, "<data> 'id'")
 
         # Check for invoke param overrides — params from parent override child defaults
         invoke_params = getattr(machine, "_invoke_params", None)
@@ -432,7 +541,7 @@ def _create_dataitem_callable(action: DataItem, evaluator: Evaluator) -> Callabl
             try:
                 value = content_fn(**kwargs)
             except Exception:
-                value = action.content
+                value = content
         else:
             value = None
 

statemachine/io/evaluators.py

@@ -5,7 +5,7 @@ neutral IR (:mod:`statemachine.io.model`) into callables, deciding *how* they ar
 evaluated:
 
 - :class:`RestrictedEvaluator` (secure default): compiles expressions with the
-  AST-whitelist evaluator (:func:`statemachine.spec_parser.parse_expr`), which
+  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
@@ -18,9 +18,13 @@ 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
-advisory for the rationale.
+(code execution) and GHSA-fj3w-533r-fvf6 (file disclosure) advisories for the rationale.
 """
 
 import ast
@@ -82,13 +86,17 @@ def _resolvable_model_attr(name: str, model) -> bool:
 def variable_hook(name: str) -> Callable:
     """Resolve a datamodel name at call time.
 
-    Looks the name up in the call kwargs first (engine-provided variables such as
-    ``_event``, ``_name``, ``machine``), then falls back to a (non-protected, non-private)
-    attribute of ``machine.model``. Mirrors the namespace built by :func:`_eval`.
+    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 in 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):
@@ -109,7 +117,7 @@ def cond_variable_hook(name: str) -> Callable:
     """
 
     def resolver(*args, **kwargs):
-        if name in 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):
@@ -166,9 +174,20 @@ class Evaluator(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-whitelist evaluation, no ``eval``/``exec``.
+    """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
@@ -208,6 +227,12 @@ class RestrictedEvaluator:
         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:
@@ -235,7 +260,7 @@ class PythonEvaluator:
 
     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 whitelist rejects —
+        # 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
@@ -263,6 +288,9 @@ class PythonEvaluator:
         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).

statemachine/io/invoke.py

@@ -20,6 +20,7 @@ from typing import Any
 from ..invoke import IInvoke
 from ..invoke import InvokeContext
 from .actions import ExecuteBlock
+from .actions import _ensure_writable_target
 from .evaluators import Evaluator
 from .model import InvokeDefinition
 from .model import StateMachineDefinition
@@ -57,6 +58,12 @@ class Invoker:
         self._base_dir: str = base_dir
         self._evaluator: Evaluator = evaluator
 
+        # A static ``src`` is known at load time, so reject it now (like <data src> /
+        # <script>) for a clean, propagating error. A dynamic ``srcexpr`` can only be
+        # resolved at runtime and is gated again in ``_resolve_content``.
+        if definition.content is None and definition.src is not None:
+            self._evaluator.ensure_external_src_allowed("<invoke src=...>")
+
         # Duck-typed attributes for InvokeManager
         self.invoke_id: "str | None" = definition.id
         self.idlocation: "str | None" = definition.idlocation
@@ -76,6 +83,7 @@ class Invoker:
 
         # Store invokeid in idlocation if specified
         if self.idlocation:
+            _ensure_writable_target(self.idlocation, "<invoke> 'idlocation'")
             setattr(machine.model, self.idlocation, ctx.invokeid)
 
         # Resolve invoke type
@@ -176,6 +184,10 @@ class Invoker:
         else:
             return None
 
+        # Reading a local file named by an untrusted document is a confidentiality risk,
+        # so it is gated on the trust level (mirrors <script> / <data src>).
+        self._evaluator.ensure_external_src_allowed("<invoke src=...>")
+
         # Handle file: URIs and relative paths
         if src.startswith("file:"):
             path = Path(src.removeprefix("file:"))