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

{python_statemachine-3.2.0.dist-info → python_statemachine-3.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-statemachine
-Version: 3.2.0
+Version: 3.2.1
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>

{python_statemachine-3.2.0.dist-info → python_statemachine-3.2.1.dist-info}/RECORD

@@ -1,23 +1,23 @@
-statemachine/__init__.py,sha256=QiHL_KGtaPxEuPtKCpwb6DssApC1jcalKYrkfNgMKc4,445
+statemachine/__init__.py,sha256=roXmQG7d48QWxlQUM94bfLMVTiJ6iZnqnhQ-qkkFHv8,445
 statemachine/callbacks.py,sha256=LKX9GnDhN64yYh2EvDEYNJg0-N61Kmyd0aqTZKxujM4,14526
 statemachine/configuration.py,sha256=MblvaBwEOyooYc4Vzo-qeryF9sEmx9mdtZDY0Gf_uRU,5991
-statemachine/dispatcher.py,sha256=DyRqwgr7gXom312BIPsNZiueq5n8jNp1dBDExm7mG_g,8109
+statemachine/dispatcher.py,sha256=fyJKGhOdmHAzsBB7zfoU1hPAauoC7IEyBC2C-yYzBcw,8438
 statemachine/event.py,sha256=hYVvsNpsY0-OSebwDEpxdLXadoJS_G5pmDe34hRqnFk,7645
 statemachine/event_data.py,sha256=7_hoE0cp-0uW71Kk3erO3eYM6anTT5X3slGMcehIGIo,3111
 statemachine/events.py,sha256=11GyX8GYpsSwvW0v1b4zHUGhzKRoqNjQYtuDj8NvqOM,1212
-statemachine/exceptions.py,sha256=N6iTrin-uMyw31mbXbO6FUj0V5WGvfKaNZe6L2pV0IE,1314
+statemachine/exceptions.py,sha256=q1ZOqBmNv34mtHAzv4XHBV67BHldxtEpu3uoeTXiEYI,1317
 statemachine/factory.py,sha256=qIgDxBwa5xa0lgvTaV4QPqdYqqkXZCzlSq0sX4TjZvo,14640
 statemachine/graph.py,sha256=ngQ31YAetfQLQvdBU5cHwLQcD-wJL92axPJ2sUeCu1g,1999
 statemachine/i18n.py,sha256=NLvGseaORmQ0G-V_J8tkjoxh_piWMOm2CI6mBQpLamc,362
 statemachine/invoke.py,sha256=5B7XNvBFnQaKByoYM1VbRlJvJyEwXn1C0QKUCaRjmpU,24908
 statemachine/mixins.py,sha256=8qxZZfBwVdFcr3oPFVWHGzgmAubH6VgQus5x3c6VEE0,1706
 statemachine/model.py,sha256=OylI3FjMiHpYyDl9mtK1zEJMeSvemaN4giQDonpc8kI,211
-statemachine/orderedset.py,sha256=7y4Hu6vVD0LHTSJ5iTB9F-faRw0326EubR3AOrpZAHE,2570
+statemachine/orderedset.py,sha256=a2FqEAAKja6E0Bu5O5Lzbd18V4hECrrCbinguIdzTjk,2794
 statemachine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 statemachine/registry.py,sha256=TmHfVU7HgaG43slG5lh8EL-8237Fm8r2UkwDj8u-t0c,700
 statemachine/signature.py,sha256=-IiRYJScx4cDKny3ictQvHwQBbaCyxWpRKSgQksMT0E,9834
-statemachine/spec_parser.py,sha256=fjiUjtzTAk6UliNsdbeInqrnp38cfHeYVlgMrbqrzxc,13450
-statemachine/state.py,sha256=kSHeJh1BlSpeDPxMKCCpwIJqzx4MPdXYZ1S24kki4os,15426
+statemachine/spec_parser.py,sha256=hc4dTr8gjKjg-xyG9UA8iTQ-t8EY6Df361fDv5QFsO8,16133
+statemachine/state.py,sha256=Do-Fw5ZUYQBAXjXmBIGzQ9hnmn7TrmdmpvP8z6Nqp6g,15436
 statemachine/statemachine.py,sha256=27TRypjsh3lwlAGZAwqrt-Cnka65uBoaxMWrU27gg6M,19941
 statemachine/states.py,sha256=NRHtATtb-2Ac2nwzSn5OfHwzOSxI2FLeNR8o1v84USs,4827
 statemachine/transition.py,sha256=JtGABHJ6inZrneI70bgu4ir2BZ2YQagcYX9l6TcsHSc,6912
@@ -29,7 +29,7 @@ statemachine/contrib/timeout.py,sha256=VXkdLpxNeUKihkbtLv8XTWdG-meQlSFtxJfcxXgV8
 statemachine/contrib/weighted.py,sha256=lzcopcY0EzjJb-N4APJJc7AlgZIPtthTbBizKaDtOIk,6787
 statemachine/contrib/diagram/__init__.py,sha256=mvTluFDnhE2OzTeOhyU7aQebl79LIOsvOiNFAVIldww,7730
 statemachine/contrib/diagram/__main__.py,sha256=iPpiz09xKqtAjrhONS99OYp6R2dQ6Anbhw1qPIN8ELo,80
-statemachine/contrib/diagram/extract.py,sha256=oNy67KToH7zxgEIPavOvgbpoYTSkM3iWB-Zas1_lcqY,9854
+statemachine/contrib/diagram/extract.py,sha256=0X9RsHFgQgxDGaz6GGbFnJacZyxRO7sV7PolpWiFbdw,9869
 statemachine/contrib/diagram/formatter.py,sha256=lYdBGO3VSZnM9OipyNsuA6StMEEjrRdnksm9MmzKXBA,4724
 statemachine/contrib/diagram/model.py,sha256=pn7dzrt8U8TOn4A-Jg1Rc3b1UUlTgs75WfR2x-xtEuc,1451
 statemachine/contrib/diagram/sphinx_ext.py,sha256=HcEXU-aYz8da02XPkZKpF5HDF0XPBGGg9FCz8MtI1C8,10338
@@ -38,35 +38,35 @@ statemachine/contrib/diagram/renderers/dot.py,sha256=VkWMVP1DLl1YUEUZVmBVSNQVbAG
 statemachine/contrib/diagram/renderers/mermaid.py,sha256=3N1z0klonL768exBcWp3WLMuWUgCpRso2UhpdnvHYhY,13424
 statemachine/contrib/diagram/renderers/table.py,sha256=PLVfwTIZHtv7uK3smAfN1owAOEunkBRHyEkh5ygVcfw,3711
 statemachine/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-statemachine/engines/async_.py,sha256=_n7x5IDu6bucBjE7PFdHBzYwrEcPd-iRxDfMc4FE9HI,22537
-statemachine/engines/base.py,sha256=kAgpDu8iTejPBXp_4casK_rQuHkL_G3Njph8iuXzDiw,37954
+statemachine/engines/async_.py,sha256=luSBqLaemcLoaI8PGcpWV8L-VMyEQhOZ2Tl57bEPuP4,22991
+statemachine/engines/base.py,sha256=qVMe0s-L4aSXA4XfQ9MUnzGHgS1ifTZ7F6rSujTOqLE,38465
 statemachine/engines/sync.py,sha256=F_bt4z1KLLcFCP77E9SNWDJMWiMTexE0iOU2XAd_x5A,9153
-statemachine/io/__init__.py,sha256=i5rGVI1ETu1hH0W8qtQMqK0WrFCYLPdV-s5VXh9vOSo,2062
-statemachine/io/actions.py,sha256=FmRjPFJkcQwtxSEaOXbvu3S5vETai2j5r8mC_4eZ8Og,18624
+statemachine/io/__init__.py,sha256=BMA91t_PY0fmsjIfMeq8pQ6Cs4KS1gxyrZj_DtMntRA,2769
+statemachine/io/actions.py,sha256=wd0bgL63Rdi2a6RUkobeIvAYaNrNpJHVjZ7kP5P9blw,24377
 statemachine/io/builder.py,sha256=yNaQrtFfbs55uRd-loZ-Vs5061liwM-np-B_2ZuJO1I,8350
 statemachine/io/class_factory.py,sha256=H8zxsfrjLw7L_X2g2hoXb2CjpHxTftsoBmPBWIcen-4,9557
-statemachine/io/evaluators.py,sha256=tMcovIr6dhysLRaxUjYbNmPu3jvOzpHOZDjevUnGEMU,10640
+statemachine/io/evaluators.py,sha256=A6g_o_8GuYMcSFOWJ1dsVRzr06ddikybCI-xAbY3vhY,12178
 statemachine/io/interpreter.py,sha256=FQUXUlt1PSPzFHyixiLNXcN-7KYBM_i5RAFPRPLu6TE,5567
-statemachine/io/invoke.py,sha256=wbeSJSlDLEvS7hXSznpMT7wd8GDcVsQSXGgFr67zVrI,9877
-statemachine/io/loader.py,sha256=GbCF0MoLxcRa84zZOZPsJpdIUeodFGcsFoWE_Wk4bqQ,6442
+statemachine/io/invoke.py,sha256=iPYck_vP2vh7-bRXkMwOYHryrXCqWxNhLzFE8uiG6L8,10632
+statemachine/io/loader.py,sha256=g_X6NgI2mudpwHN6EoDCaDv4HsryFpO93lExPo_lOdU,7054
 statemachine/io/model.py,sha256=mTJvlbDJndX78pHfyDdEaqc9zTBWVA-OFA5xzVZbz6Y,8695
 statemachine/io/native.py,sha256=HjIOKDQIGExLMglcm8VGbga71Y1Zw-pBbKYWP-y_oiY,13758
 statemachine/io/ports.py,sha256=XoIAQfMujkEnH38t4iu766yiHycb89TNrA3owtBJU2U,2956
-statemachine/io/system_variables.py,sha256=7skuJgBL8giqzaNEyWd783xOZtVRSUHF6ETwt9fVcd4,6223
+statemachine/io/system_variables.py,sha256=yYoAJTCm1uNIp63Dyw0wSUKDJbg1gQGgWKfvBt6LyGQ,7278
 statemachine/io/validation.py,sha256=6qiDx0gMkPAehSxJu_mrW4nEF_sebHwa5Dr_njclRcw,1662
 statemachine/io/json/__init__.py,sha256=tFWoOrD9RuKEqkOpI0XifNRP7rguSGY4k-RaSCV_GnM,38
 statemachine/io/json/reader.py,sha256=40V5T-yB1i0Qg-MkK00KHRi7eDQQk4ajfzmKtKXylHs,789
 statemachine/io/schemas/statechart.schema.json,sha256=5yNIS4M7OV6GE2doAWMk_Jct-qDyb5kQ-Dq95Es9KbM,7862
-statemachine/io/scxml/__init__.py,sha256=iGS763p9fZ6A7NVuEVpDVOS303q0dr5N4kVfOZ37jsk,660
-statemachine/io/scxml/processor.py,sha256=Ru_YQAA1OVXNS9AqfN2myL5POq-C4kI1Vpef-eO7k2M,1532
-statemachine/io/scxml/reader.py,sha256=CNUI9ARDJswRZDKqJSBY98Uoa5rQJsIU-kS9Uu5cmzg,17057
+statemachine/io/scxml/__init__.py,sha256=0CMGGfpOaindNGb6VOkMn7Z4nGqK3iJ3sMZcS531Kaw,972
+statemachine/io/scxml/processor.py,sha256=wk6Tt7yTf2GxCwx5S3eT9NInMsObspPmpQFLTNkacSk,1532
+statemachine/io/scxml/reader.py,sha256=gp6tglHXdNxnPa9jNoo9jvRqNUfIr3O_DjCQJQijbD4,17821
 statemachine/io/yaml/__init__.py,sha256=oMapUmquV7hb5qIGMfjDZmDHNq2fqqjJw6LOgGNKeC4,79
 statemachine/io/yaml/reader.py,sha256=mf2FaBttxQuCniSM-vHhSYDGaNLQdzRLoMUHO2kZ0xA,2208
 statemachine/locale/en/LC_MESSAGES/statemachine.po,sha256=_HrrNLQK1krOb56x5Pf1S6LihwaPwhN9_T0PUvumRA0,5338
 statemachine/locale/hi_IN/LC_MESSAGES/statemachine.po,sha256=O15jEhCNATAu6O2WhQ9RhQISB6Ueje2xbbTfEotnVSc,7948
 statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po,sha256=X6-fU4JfK7VPFCRuLQ-4J-YUMF9N_RwhZ1DdCUvn74Y,5814
 statemachine/locale/zh_CN/LC_MESSAGES/statemachine.po,sha256=0_54wD7bl3RBMlYyokNFUdgMCx_1MbKzclxBUwmCNEs,5363
-python_statemachine-3.2.0.dist-info/METADATA,sha256=Vdy46mBCvmA04ruIBaTS9XklmK72ip3yycmrzgCWu48,12642
-python_statemachine-3.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_statemachine-3.2.0.dist-info/licenses/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
-python_statemachine-3.2.0.dist-info/RECORD,,
+python_statemachine-3.2.1.dist-info/METADATA,sha256=1IBKPLjl5g4Ui0PIp6lUfCF8zL8yJ9_KLcKhmtsrM-w,12642
+python_statemachine-3.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+python_statemachine-3.2.1.dist-info/licenses/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
+python_statemachine-3.2.1.dist-info/RECORD,,

{python_statemachine-3.2.0.dist-info → python_statemachine-3.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

statemachine/__init__.py

@@ -8,7 +8,7 @@ from .statemachine import TModel
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "3.2.0"
+__version__ = "3.2.1"
 
 __all__ = [
     "StateChart",

statemachine/contrib/diagram/extract.py

@@ -91,7 +91,7 @@ def _extract_state(
 
     return DiagramState(
         id=state.id,
-        name=state.name,
+        name=str(state.name),
         type=state_type,
         actions=actions,
         children=children,
@@ -125,7 +125,7 @@ def _format_event_names(transition: "Transition") -> str:
             continue
         if eid not in seen_ids:  # pragma: no branch
             seen_ids.add(eid)
-            display.append(event.name if event.name else eid)
+            display.append(str(event.name) if event.name else eid)
 
     return " ".join(display)
 
@@ -279,7 +279,7 @@ def extract(machine_or_class: "MachineRef") -> DiagramGraph:
     _resolve_initial_states(states)
 
     return DiagramGraph(
-        name=machine.name,
+        name=str(machine.name),
         states=states,
         transitions=transitions,
         compound_state_ids=compound_ids,

statemachine/dispatcher.py

@@ -14,6 +14,7 @@ from .event import Event
 from .exceptions import InvalidDefinition
 from .i18n import _
 from .signature import SignatureAdapter
+from .spec_parser import UnsupportedExpression
 from .spec_parser import custom_and
 from .spec_parser import operator_mapping
 from .spec_parser import parse_boolean_expr
@@ -118,7 +119,10 @@ class Listeners:
 
         try:
             expression = parse_boolean_expr(spec.func, take_callback_partial, operator_mapping)
-        except SyntaxError as err:
+        except (SyntaxError, UnsupportedExpression) as err:
+            # ``UnsupportedExpression`` comes from the AST allowlist rejecting a node
+            # kind that cannot appear in a boolean expression (e.g. ``"user.age"``).
+            # Errors raised while resolving names are not parse errors and propagate.
             raise InvalidDefinition(
                 _("Failed to parse boolean expression '{}'").format(spec.func)
             ) from err

statemachine/engines/async_.py

@@ -71,17 +71,27 @@ class AsyncEngine(BaseEngine):
     # --- Callback dispatch overrides (async versions of BaseEngine methods) ---
 
     async def _get_args_kwargs(
-        self, transition: "Transition", trigger_data: TriggerData, target: "State | None" = None
+        self,
+        transition: "Transition",
+        trigger_data: TriggerData,
+        target: "State | None" = None,
+        source: "State | None" = None,
     ):
-        cache_key = (id(transition), id(trigger_data), id(target))
+        cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
         if cache_key in self._cache:
             return self._cache[cache_key]
 
         event_data = EventData(trigger_data=trigger_data, transition=transition)
+        # See the sync engine for the rationale: bind `state`/`target` to the
+        # entered state and `state`/`source` to the exited state, keeping the
+        # generic enter/exit callbacks symmetric across compound boundaries.
         if target:
             event_data.state = target
             event_data.target = target
+        if source:
+            event_data.state = source
+            event_data.source = source
 
         args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -173,7 +183,9 @@ class AsyncEngine(BaseEngine):
             if info.state is not None:  # pragma: no branch
                 self._invoke_manager.cancel_for_state(info.state)
 
-            args, kwargs = await self._get_args_kwargs(info.transition, trigger_data)
+            args, kwargs = await self._get_args_kwargs(
+                info.transition, trigger_data, source=info.state
+            )
 
             if info.state is not None:  # pragma: no branch
                 self._debug("%s Exiting state: %s", self._log_id, info.state)

statemachine/engines/base.py

@@ -419,19 +419,30 @@ class BaseEngine:
         return result
 
     def _get_args_kwargs(
-        self, transition: Transition, trigger_data: TriggerData, target: "State | None" = None
+        self,
+        transition: Transition,
+        trigger_data: TriggerData,
+        target: "State | None" = None,
+        source: "State | None" = None,
     ):
         # Generate a unique key for the cache, the cache is invalidated once per loop
-        cache_key = (id(transition), id(trigger_data), id(target))
+        cache_key = (id(transition), id(trigger_data), id(target), id(source))
 
         # Check the cache for existing results
         if cache_key in self._cache:
             return self._cache[cache_key]
 
         event_data = EventData(trigger_data=trigger_data, transition=transition)
+        # Bind `state`/`target` to the individual state being entered, and
+        # `state`/`source` to the individual state being exited, so the generic
+        # `on_enter_state`/`on_exit_state` callbacks stay symmetric when crossing
+        # compound state boundaries (the transition only knows its own endpoints).
         if target:
             event_data.state = target
             event_data.target = target
+        if source:
+            event_data.state = source
+            event_data.source = source
 
         args, kwargs = event_data.args, event_data.extended_kwargs
 
@@ -500,7 +511,7 @@ class BaseEngine:
             if info.state is not None:  # pragma: no branch
                 self._invoke_manager.cancel_for_state(info.state)
 
-            args, kwargs = self._get_args_kwargs(info.transition, trigger_data)
+            args, kwargs = self._get_args_kwargs(info.transition, trigger_data, source=info.state)
 
             # Execute `onexit` handlers — same per-block error isolation as onentry.
             if info.state is not None:  # pragma: no branch

statemachine/exceptions.py

@@ -36,7 +36,7 @@ class TransitionNotAllowed(StateMachineError):
     def __init__(self, event: "Event | None", configuration: MutableSet["State"]):
         self.event = event
         self.configuration = configuration
-        name = ", ".join([s.name for s in configuration])
+        name = ", ".join(str(s.name) for s in configuration)
         msg = _("Can't {} when in {}.").format(
             self.event and self.event.name or "transition", name
         )

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,9 +8,11 @@ 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
@@ -37,6 +39,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 +240,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 +328,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)
@@ -354,6 +439,7 @@ def create_send_action_callable(  # noqa: C901
         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 +494,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 +539,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:"))

statemachine/io/loader.py

@@ -3,7 +3,7 @@
 :func:`load` is the simple entry point: give it a file path (format detected by
 extension) or inline content (with an explicit ``format=``) and it returns the
 ready-to-instantiate :class:`~statemachine.statemachine.StateChart` class. It is
-**secure by default** — expressions are evaluated by a restricted AST-whitelist
+**secure by default** — expressions are evaluated by a restricted AST-allowlist
 evaluator and ``<script>`` / arbitrary Python is rejected unless ``trusted=True``.
 
 For advanced scenarios (a document declaring several statecharts, or SCXML files
@@ -39,6 +39,20 @@ def _chdir(new_dir: Path):
         os.chdir(original)
 
 
+def _is_existing_file(source: str) -> bool:
+    """Whether ``source`` names an existing file, treating "too long"/invalid as not a file.
+
+    A long single-line inline document (e.g. minified JSON) is not a path, but reaches
+    :meth:`Path.is_file`, which on some platforms raises ``OSError`` (``ENAMETOOLONG``) or
+    ``ValueError`` (embedded NUL) instead of returning ``False``. Swallow those so inline
+    content is never mistaken for a crash; a real, resolvable path still returns ``True``.
+    """
+    try:
+        return Path(source).is_file()
+    except (OSError, ValueError):
+        return False
+
+
 def _resolve_source(source: "str | Path", format: "str | None"):
     """Return ``(text, format_name, location_hint, base_dir)`` for a source.
 
@@ -48,7 +62,7 @@ def _resolve_source(source: "str | Path", format: "str | None"):
     """
     if isinstance(source, Path):
         path: "Path | None" = source
-    elif "\n" not in source and Path(source).is_file():
+    elif "\n" not in source and _is_existing_file(source):
         path = Path(source)
     else:
         path = None
@@ -140,7 +154,7 @@ def load(
         format: explicit format name (``"scxml"``, ``"json"``, ``"yaml"``),
             overriding extension detection and required for inline content.
         trusted: when ``False`` (default), expressions are evaluated by a restricted
-            AST-whitelist evaluator and ``<script>`` / arbitrary Python is rejected.
+            AST-allowlist evaluator and ``<script>`` / arbitrary Python is rejected.
             When ``True``, expressions and scripts are evaluated as arbitrary Python.
         validate: when ``True`` (native JSON/YAML only), validate the document against
             the published JSON Schema before building (requires the ``[validation]``

statemachine/io/scxml/__init__.py

@@ -6,7 +6,10 @@ provides a Python datamodel and loads SCXML through the same
 :func:`~statemachine.io.load` facade as the native JSON/YAML formats.
 
 Like every format, SCXML is loaded **secure by default** (``trusted=False`` rejects
-``<script>`` and evaluates expressions with the restricted AST-whitelist evaluator); pass
-``trusted=True`` only for documents you control. See the security note in
-:mod:`statemachine.io` and the GHSA-v4jc-pm6r-3vj8 advisory.
+``<script>`` and external ``<data src>`` / ``<invoke src>`` file references, evaluates
+expressions with the restricted AST-allowlist evaluator, confines write targets to public model
+attributes and magnitude-caps ``**``/``*``); pass ``trusted=True`` only for documents you
+control. The parser also refuses ``<!DOCTYPE>``/DTD to block XML entity-expansion bombs. See the
+security note in :mod:`statemachine.io` and the GHSA-v4jc-pm6r-3vj8, GHSA-fj3w-533r-fvf6,
+GHSA-v3qq-3xvg-m77g, GHSA-4857-ggqc-p3jc and GHSA-r8gj-366q-cgvj advisories.
 """

statemachine/io/scxml/processor.py

@@ -18,7 +18,7 @@ class SCXMLProcessor(Interpreter):
 
     Args:
         trusted: when ``False`` (default), datamodel expressions are evaluated by
-            a restricted AST-whitelist evaluator and ``<script>`` is rejected, so
+            a restricted AST-allowlist evaluator and ``<script>`` is rejected, so
             loading a document cannot execute arbitrary code. When ``True``,
             expressions and ``<script>`` are evaluated as arbitrary Python via
             ``eval``/``exec`` — only use it for SCXML you trust (see the package

statemachine/io/scxml/reader.py

@@ -3,8 +3,8 @@ import xml.etree.ElementTree as ET
 from collections.abc import Callable
 from typing import Literal
 from typing import cast
-from urllib.parse import urlparse
 
+from ...exceptions import InvalidDefinition
 from ..model import Action
 from ..model import AssignAction
 from ..model import CancelAction
@@ -47,8 +47,27 @@ def _parse_initial(initial_content: "str | None") -> list[str]:
     return initial_content.split()
 
 
+class _NoDTDTreeBuilder(ET.TreeBuilder):
+    """A tree builder that refuses documents carrying a ``<!DOCTYPE>``/DTD.
+
+    Internal entity definitions (the basis of billion-laughs / quadratic-blowup
+    expansion bombs) require a DTD, so rejecting the DOCTYPE neutralizes them at
+    parse time. Expat calls this ``doctype`` hook when it meets the declaration.
+    """
+
+    def doctype(self, name, pubid, system):  # noqa: D102 - expat callback
+        raise InvalidDefinition(
+            "DOCTYPE/DTD is not allowed in SCXML documents (XML entity-expansion protection)."
+        )
+
+
+def _fromstring_no_dtd(scxml_content: str) -> ET.Element:
+    """Parse SCXML text rejecting any DOCTYPE (see :class:`_NoDTDTreeBuilder`)."""
+    return ET.fromstring(scxml_content, parser=ET.XMLParser(target=_NoDTDTreeBuilder()))
+
+
 def parse_scxml(scxml_content: str) -> StateMachineDefinition:  # noqa: C901
-    root = ET.fromstring(scxml_content)
+    root = _fromstring_no_dtd(scxml_content)
     strip_namespaces(root)
 
     scxml = root if root.tag == "scxml" else root.find(".//scxml")
@@ -114,16 +133,12 @@ def parse_datamodel(root: ET.Element) -> "DataModel | None":
     for datamodel_elem in _find_own_datamodel_elements(root):
         for data_elem in datamodel_elem.findall("data"):
             content = data_elem.text and re.sub(r"\s+", " ", data_elem.text).strip() or None
-            src = data_elem.attrib.get("src")
-            src_parsed = urlparse(src) if src else None
-            if src_parsed and src_parsed.scheme == "file" and content is None:
-                with open(src_parsed.path) as f:
-                    content = f.read()
-
+            # An external ``src`` is kept as a raw string; resolving it (reading the file)
+            # is deferred to datamodel compilation, where the trust policy can gate it.
             data_model.data.append(
                 DataItem(
                     id=data_elem.attrib["id"],
-                    src=src,
+                    src=data_elem.attrib.get("src"),
                     expr=data_elem.attrib.get("expr"),
                     content=content,
                 )

statemachine/io/system_variables.py

@@ -18,13 +18,23 @@ from typing import Any
 
 @dataclass
 class _Data:
-    kwargs: dict
+    """The ``_event.data`` payload view.
+
+    The raw payload dict is stored under a private (``_``-prefixed) name so a restricted
+    expression cannot hand back the underlying dict via ``_event.data.kwargs``; only the
+    individual payload fields (``_event.data.<field>``) are reachable.
+    """
+
+    _kwargs: dict
 
     def __getattr__(self, name):
-        return self.kwargs.get(name, None)
+        if name == "_kwargs":
+            # Guard against unbounded recursion before the field is set (e.g. copy/pickle).
+            raise AttributeError(name)
+        return self._kwargs.get(name, None)
 
     def get(self, name, default=None):
-        return self.kwargs.get(name, default)
+        return self._kwargs.get(name, default)
 
 
 class OriginTypeSCXML(str):
@@ -51,15 +61,21 @@ class EventDataWrapper:
     """
 
     def __init__(self, event_data=None, *, trigger_data=None):
-        self.event_data = event_data
+        # The engine carriers are stored under private (``_``-prefixed) names so a
+        # restricted expression cannot reach them (``_event.event_data`` /
+        # ``_event.trigger_data``) and pivot to the machine/interpreter/State. The
+        # restricted evaluator blocks attribute access to ``_``-prefixed names, and this
+        # class deliberately exposes NO public attribute or ``__getattr__`` forward that
+        # would hand them back (GHSA-v3qq-3xvg-m77g).
+        self._event_data = event_data
         if trigger_data is not None:
-            self.trigger_data = trigger_data
+            self._trigger_data = trigger_data
         elif event_data is not None:
-            self.trigger_data = event_data.trigger_data
+            self._trigger_data = event_data.trigger_data
         else:
             raise ValueError("Either event_data or trigger_data must be provided")
 
-        td = self.trigger_data
+        td = self._trigger_data
         self.sendid = td.send_id
         self.invokeid = td.kwargs.get("_invokeid", "")
         if td.event is None or td.event.internal:
@@ -76,25 +92,20 @@ class EventDataWrapper:
         """Create an EventDataWrapper directly from a TriggerData (no EventData needed)."""
         return cls(trigger_data=trigger_data)
 
-    def __getattr__(self, name):
-        if self.event_data is not None:
-            return getattr(self.event_data, name)
-        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
     def __eq__(self, value):
         "This makes SCXML test 329 pass. It assumes that the event is the same instance"
         return isinstance(value, EventDataWrapper)
 
     @property
     def name(self):
-        if self.event_data is not None:
-            return self.event_data.event
-        return str(self.trigger_data.event) if self.trigger_data.event else None
+        if self._event_data is not None:
+            return self._event_data.event
+        return str(self._trigger_data.event) if self._trigger_data.event else None
 
     @property
     def data(self):
         "Property used to access the event payload (the SCXML ``_event.data``)."
-        td = self.trigger_data
+        td = self._trigger_data
         if td.kwargs:
             return _Data(td.kwargs)
         elif td.args and len(td.args) == 1:
@@ -113,15 +124,19 @@ class IOProcessor:
     """
 
     def __init__(self, interpreter, machine):
-        self.interpreter = interpreter
-        self.machine = machine
+        # Stored under private (``_``-prefixed) names so a restricted expression cannot
+        # reach the interpreter/machine via ``_ioprocessors.interpreter`` /
+        # ``_ioprocessors.machine`` and mutate the process-shared engine
+        # (GHSA-v3qq-3xvg-m77g). Only the SCXML-visible ``location`` stays public.
+        self._interpreter = interpreter
+        self._machine = machine
 
     def __getitem__(self, name: str):
         return self
 
     @property
     def location(self):
-        return self.machine.name
+        return self._machine.name
 
     def get(self, name: str):
         return getattr(self, name)

statemachine/orderedset.py

@@ -62,10 +62,14 @@ class OrderedSet(MutableSet[T]):
     >>> s[2]
     3
 
-    >>> eval(repr(OrderedSet(['a', 'b', 'c'])))
-    OrderedSet(['a', 'b', 'c'])
+    >>> s[-1]
+    3
 
+    >>> s[-3]
+    1
 
+    >>> eval(repr(OrderedSet(['a', 'b', 'c'])))
+    OrderedSet(['a', 'b', 'c'])
 
     """
 
@@ -84,10 +88,15 @@ class OrderedSet(MutableSet[T]):
         self._d.pop(x, None)
 
     def __getitem__(self, index) -> T:
+        original_index = index
+        if index < 0:
+            index += len(self)
+        if index < 0:
+            raise IndexError(f"index {original_index} out of range")
         try:
             return next(itertools.islice(self._d, index, index + 1))
         except StopIteration as e:
-            raise IndexError(f"index {index} out of range") from e
+            raise IndexError(f"index {original_index} out of range") from e
 
     def __contains__(self, x: object) -> bool:
         return self._d.__contains__(x)

statemachine/spec_parser.py

@@ -19,6 +19,15 @@ comparison_repr = {
 }
 
 
+class UnsupportedExpression(ValueError):
+    """The expression contains a structure that is not on the parser allowlist.
+
+    Distinguishes a rejected expression from errors raised by the ``variable_hook``
+    while resolving names, so callers can report each one properly. Inherits from
+    ``ValueError`` to keep the previous behavior for callers catching it.
+    """
+
+
 def _unique_key(left, right, operator) -> str:
     left_key = getattr(left, "unique_key", "")
     right_key = getattr(right, "unique_key", "")
@@ -128,7 +137,7 @@ class Functions:
     def get(cls, func_id):
         func_id = func_id.lower()
         if func_id not in cls.registry:
-            raise ValueError(f"Unsupported function: {func_id}")
+            raise UnsupportedExpression(f"Unsupported function: {func_id}")
         return cls.registry[func_id]
 
 
@@ -231,7 +240,7 @@ def build_attribute(value_expr: Callable, attr: str) -> Callable:
 def build_expression(  # noqa: C901
     node, variable_hook, operator_mapping, allow_value_nodes: bool = False
 ):
-    """Build a callable from an AST node using a whitelist of allowed structures.
+    """Build a callable from an AST node using an allowlist of allowed structures.
 
     Args:
         allow_value_nodes: when ``True``, value-producing structures (arithmetic,
@@ -265,7 +274,7 @@ def build_expression(  # noqa: C901
                 expressions.append(expression)
             return reduce(custom_and, expressions)
         case ast.Call(func=ast.Name(id=func_id)):
-            # Only whitelisted functions from the registry (e.g. ``In(...)``) are
+            # Only allowlisted functions from the registry (e.g. ``In(...)``) are
             # callable. Method calls (``obj.method()``) have an ``ast.Attribute``
             # func and fall through to the ``case _`` guard below — this prevents
             # using calls as a sandbox-escape vector.
@@ -276,10 +285,13 @@ def build_expression(  # noqa: C901
             return operator_mapping[type(node.op)](recurse(node.operand))
         case ast.UnaryOp(op=(ast.USub() | ast.UAdd())) if allow_value_nodes:
             return build_unaryop(unary_operators[type(node.op)], recurse(node.operand))
-        case ast.BinOp() if allow_value_nodes and type(node.op) in binary_operators:
-            return build_binop(
-                binary_operators[type(node.op)], recurse(node.left), recurse(node.right)
-            )
+        case ast.BinOp() if allow_value_nodes:
+            op_type = type(node.op)
+            if op_type not in binary_operators:
+                # e.g. bitwise ``^``/``|``/``<<`` are outside the allowlist. (``**`` and ``*``
+                # are allowed but magnitude-capped — see ``binary_operators``.)
+                raise ValueError(f"Binary operator '{op_type.__name__}' is not allowed")
+            return build_binop(binary_operators[op_type], recurse(node.left), recurse(node.right))
         case ast.List(elts=elts) if allow_value_nodes:
             return build_collection(list, [recurse(e) for e in elts])
         case ast.Tuple(elts=elts) if allow_value_nodes:
@@ -300,14 +312,16 @@ def build_expression(  # noqa: C901
             # without underscore-attribute access or method calls, it cannot reach
             # type objects.
             if attr.startswith("_"):
-                raise ValueError(f"Attribute access to '{attr}' is not allowed")
+                raise UnsupportedExpression(f"Attribute access to '{attr}' is not allowed")
             return build_attribute(recurse(node.value), attr)
         case ast.Name(id=name):
             return variable_hook(name)
         case ast.Constant(value=value):
             return build_constant(value)
         case _:
-            raise ValueError(f"Unsupported expression structure: {node.__class__.__name__}")
+            raise UnsupportedExpression(
+                f"Unsupported expression structure: {node.__class__.__name__}"
+            )
 
 
 def parse_boolean_expr(expr, variable_hook, operator_mapping):
@@ -315,8 +329,10 @@ def parse_boolean_expr(expr, variable_hook, operator_mapping):
     if expr.strip() == "":
         raise SyntaxError("Empty expression")
 
-    # Optimization trying to avoid parsing the expression if not needed
-    if "!" not in expr and " " not in expr and "In(" not in expr:
+    # Optimization: a lone identifier can only be a variable name, so there is
+    # nothing to parse. Anything else (operators, comparisons, spaces, calls)
+    # goes through the parser.
+    if expr.isidentifier():
         return variable_hook(expr)
     expr = replace_operators(expr)
     tree = ast.parse(expr, mode="eval")
@@ -324,7 +340,7 @@ def parse_boolean_expr(expr, variable_hook, operator_mapping):
 
 
 def parse_expr(expr: str, variable_hook: Callable) -> Callable:
-    """Parse a value expression into a callable using the restricted AST whitelist.
+    """Parse a value expression into a callable using the restricted AST allowlist.
 
     Unlike :func:`parse_boolean_expr`, this does not apply the DSL operator
     replacement (``!``/``^``/``v``) and does not coerce the top-level result to
@@ -333,7 +349,7 @@ def parse_expr(expr: str, variable_hook: Callable) -> Callable:
     without :func:`eval`.
 
     Raises:
-        ValueError: if the expression uses a structure outside the whitelist
+        ValueError: if the expression uses a structure outside the allowlist
             (e.g. attribute access to dunders, method calls, lambdas).
         SyntaxError: if the expression is empty or not valid Python.
     """
@@ -358,14 +374,52 @@ operator_mapping = {
     ast.NotEq: build_custom_operator(operator.ne),
 }
 
+# Result-size caps for the two operators that can blow up cheaply. Ordinary scalar
+# arithmetic (``x * 2``, ``x ** 2``) is well under these; the caps only reject the
+# denial-of-service forms (``9**9**9`` bignum, ``[0]*20000000`` sequence replication).
+_MAX_POW_RESULT_BITS = 4096
+_MAX_SEQUENCE_LEN = 1_000_000
+
+
+def _guarded_pow(base, exp):
+    """``**`` with a magnitude cap (GHSA-r8gj-366q-cgvj).
+
+    ``int ** int`` can allocate a giant bignum from a tiny expression (``9**9**9`` is a
+    ~370-million-digit number). The result size is estimated *before* computing, so the
+    allocation never happens. Non-integer operands (floats overflow to ``inf`` instead of
+    growing without bound) are passed straight through.
+    """
+    if isinstance(base, int) and isinstance(exp, int) and exp > 0 and base not in (0, 1, -1):
+        if base.bit_length() * exp > _MAX_POW_RESULT_BITS:
+            raise ValueError("'**' result is too large for the restricted evaluator")
+    return operator.pow(base, exp)
+
+
+def _guarded_mul(a, b):
+    """``*`` with a sequence-replication cap (GHSA-r8gj-366q-cgvj).
+
+    ``seq * n`` (list/str/bytes/tuple times an int) can allocate an enormous object from a
+    12-character expression (``[0]*20000000``). The resulting length is checked *before*
+    allocating. Scalar numeric multiplication is unaffected.
+    """
+    for seq, n in ((a, b), (b, a)):
+        if isinstance(seq, (str, bytes, bytearray, list, tuple)) and isinstance(n, int):
+            if n > 0 and n * len(seq) > _MAX_SEQUENCE_LEN:
+                raise ValueError("'*' repetition is too large for the restricted evaluator")
+    return operator.mul(a, b)
+
+
+# ``**`` and ``*`` stay available for ordinary arithmetic but are wrapped so a tiny untrusted
+# expression cannot exhaust CPU/memory (GHSA-r8gj-366q-cgvj). ``trusted=True`` uses the full
+# Python evaluator instead, without these caps.
 binary_operators = {
     ast.Add: operator.add,
     ast.Sub: operator.sub,
-    ast.Mult: operator.mul,
+    ast.Mult: _guarded_mul,
     ast.Div: operator.truediv,
     ast.FloorDiv: operator.floordiv,
     ast.Mod: operator.mod,
-    ast.Pow: operator.pow,
+    ast.Pow: _guarded_pow,
 }
 
 unary_operators = {

statemachine/state.py

@@ -296,7 +296,7 @@ class State:
         )
 
     def __str__(self):
-        return self.name
+        return str(self.name)
 
     @property
     def id(self) -> str:
@@ -308,7 +308,7 @@ class State:
             self.value = id
         if not self.name:
             self.name = humanize_id(self._id)
-        self._hash = hash((self.name, self._id))
+        self._hash = hash((str(self.name), self._id))
 
         return self