messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/config/state.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Synchronous **read side** for transform-accessible state (cross-message correlation, ADR 0005).
+
+A Handler **declares** writes by returning :class:`~messagefoundry.config.wiring.SetState` (applied
+exactly-once inside the routed→outbound handoff transaction); it **reads** them back synchronously via
+:func:`state_get`. Handlers are pure synchronous functions and a store read is async, so a read can't
+await the DB: instead the engine keeps an in-memory **read-through cache** of the state table (loaded
+at startup, updated as writes commit), and publishes a read-only **view** of it as the active state
+for the duration of each router/transform run — exactly how :mod:`messagefoundry.config.code_sets`
+publishes the active code sets. :func:`state_get` resolves against that view synchronously.
+
+**Layering (information hiding).** This config-layer module owns only the active-view *holder* + the
+accessor + the publish helpers (:func:`activated`/:func:`set_active`/:func:`reset`). It does **not**
+import the store: the store owns the cache and exposes it as a ``StateView`` (the read-only mapping
+``{(namespace, key): decrypted_value}``); the runner *bridges* the two by publishing
+``store.state_view()`` here around each run. So the config layer stays free of any store dependency,
+matching the one-way dependency direction (CLAUDE.md §4).
+
+**Consistency caveat (ADR 0005).** The view is the live cache, so a read reflects every committed
+write as of the call. Reads are *not* linearized with concurrent sibling-handler writes — fine for
+read-mostly correlation (patient-id mapping); a race-sensitive read-modify-write within one namespace
+needs author care. See docs/CONFIGURATION.md.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+
+from messagefoundry.config.wiring import StateValue
+
+__all__ = [
+    "StateView",
+    "state_get",
+    "set_active",
+    "reset",
+    "activated",
+]
+
+#: The engine-published read view: a read-only mapping ``{(namespace, key): decrypted_value}``. The
+#: store builds it (decrypting at load), so the config layer needs no store import — it only reads it.
+StateView = Mapping[tuple[str, str], StateValue]
+
+# Active view as a ContextVar (mirrors code_sets._active): the runner re-publishes the live cache view
+# around each router/transform run so a call-time state_get(...) inside a Handler resolves, a clean
+# reset restores the prior view (no leak across runs / overlapping reloads), and dry-run can publish a
+# view too. Defaults to None = "no active view" so state_get distinguishes "not running" from "empty".
+_active: ContextVar[StateView | None] = ContextVar("mefor_active_state", default=None)
+
+
+def set_active(view: StateView | None) -> Any:
+    """Publish ``view`` as the active state view and return a reset token (pass it to :func:`reset`).
+
+    For callers that can't bracket the active span with a ``with`` (e.g. an async worker publishing
+    around a single transform call). Prefer :func:`activated` where a ``with`` block fits."""
+    return _active.set(view)
+
+
+def reset(token: Any) -> None:
+    """Restore the active state view to what it was before the matching :func:`set_active`."""
+    _active.reset(token)
+
+
+@contextmanager
+def activated(view: StateView | None) -> Iterator[None]:
+    """Make ``view`` the active state view for the duration of the ``with`` block, then restore.
+
+    The runner brackets each router/transform run with it (and dry-run mirrors that), so
+    :func:`state_get` resolves at call time and the prior view is always restored — no leak."""
+    token = _active.set(view)
+    try:
+        yield
+    finally:
+        _active.reset(token)
+
+
+def state_get(namespace: str, key: str, default: StateValue = None) -> StateValue:
+    """Read ``namespace``/``key`` from the active state view synchronously; ``default`` on a miss.
+
+    Call it inside a Handler at run time::
+
+        anon = state_get("patient_anon", mrn)
+        if anon is None:
+            anon = derive_anon_id(mrn)
+            return [Send("OB_DOWNSTREAM", msg), SetState("patient_anon", mrn, anon)]
+
+    Resolves against the engine-maintained read-through cache view the runner publishes around the run
+    (it reflects every committed write as of this call — see the module note on non-linearization).
+    Unlike :func:`messagefoundry.config.wiring.code_set`, a missing **key** is **not** an error (it
+    returns ``default``): state is sparse correlation data, not a referenced config table. Calling it
+    with **no active view** (outside a run/dry-run) returns ``default`` as well — there is no state to
+    read there, and a transform must stay usable in isolation."""
+    view = _active.get()
+    if view is None:
+        return default
+    return view.get((namespace, key), default)

messagefoundry/config/tls_policy.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Shared TLS hardening policy (ASVS 11.6.2 key exchange + 12.1.4 strict X.509, WP-L3-10 code half).
+
+Pure stdlib ``ssl`` helpers, importable by ``api/`` and ``transports/`` (and the ``config`` settings
+validator) without crossing the engine's one-way dependency boundaries. Three controls:
+
+* :func:`validate_tls_ciphers` — reject an operator ``tls_ciphers`` string that would admit a
+  non-forward-secret (non-ECDHE/DHE) key exchange, so a misconfiguration cannot widen the suite below
+  policy. Run from the ``[api].tls_ciphers`` settings validator, so a bad value fails loud at load.
+* :func:`harden_kex_groups` — pin the approved ECDHE groups on a built context where the runtime
+  supports it (``SSLContext.set_groups``, Python 3.13+); on older interpreters OpenSSL already leads
+  with these groups, so it is a best-effort no-op rather than a downgrade.
+* :func:`harden_verify_flags` — OR ``ssl.VERIFY_X509_STRICT`` into a verifying context's
+  ``verify_flags`` so a presented chain must be RFC 5280-conformant (ASVS 12.1.4 strict path
+  validation). Revocation itself is delegated to the org PKI / OCSP-must-staple proxy + OS trust store
+  (ADR 0002); the engine attempts no stdlib OCSP. Guarded like ``harden_kex_groups`` for old runtimes.
+"""
+
+from __future__ import annotations
+
+import logging
+import ssl
+from collections.abc import Mapping
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "APPROVED_KEX_GROUPS",
+    "harden_kex_groups",
+    "harden_verify_flags",
+    "validate_tls_ciphers",
+]
+
+#: Approved forward-secret key-exchange groups in preference order (X25519 first). These are the modern
+#: NIST/FIPS-permitted ECDHE curves; the string is the OpenSSL group list passed to ``set_groups``.
+APPROVED_KEX_GROUPS = "X25519:secp384r1:secp256r1"
+
+
+def harden_kex_groups(ctx: ssl.SSLContext) -> None:
+    """Best-effort pin ``ctx`` to :data:`APPROVED_KEX_GROUPS`.
+
+    Uses ``SSLContext.set_groups`` where available (Python 3.13+). On older interpreters there is no
+    public API to pin groups and OpenSSL's defaults already lead with X25519/P-256/P-384, so this is a
+    deliberate no-op rather than a weakening. A runtime that rejects the group list (an unusual OpenSSL
+    build) is logged and left at its secure defaults."""
+    set_groups = getattr(ctx, "set_groups", None)
+    if set_groups is None:
+        return
+    try:
+        set_groups(APPROVED_KEX_GROUPS)
+    except (
+        ssl.SSLError,
+        ValueError,
+    ) as exc:  # pragma: no cover - depends on the linked OpenSSL build
+        logger.warning("Could not pin TLS key-exchange groups %r: %s", APPROVED_KEX_GROUPS, exc)
+
+
+def harden_verify_flags(ctx: ssl.SSLContext) -> None:
+    """Best-effort enable strict X.509 path validation on a *verifying* ``ctx`` (ASVS 12.1.4).
+
+    ORs ``ssl.VERIFY_X509_STRICT`` into ``ctx.verify_flags`` so a presented certificate chain must be
+    RFC 5280-conformant — no malformed/ambiguous fields from which revocation metadata (AIA / CRL-DP)
+    would otherwise be read. This is **strict validation, not revocation checking**: live revocation is
+    delegated to the deploying org's PKI — OCSP-must-staple at the WP-15 proxy plus the OS trust store —
+    because stdlib ``ssl`` exposes no OCSP/CRL fetch and the engine deliberately attempts none (ADR 0002).
+
+    Guarded like :func:`harden_kex_groups`: a runtime/OpenSSL build without ``VERIFY_X509_STRICT`` is a
+    deliberate no-op, not an error. Call it **only** on a context that actually verifies the peer (skip
+    the MLLP ``tls_verify=false`` / ``CERT_NONE`` path, where there is nothing to validate)."""
+    strict = getattr(ssl, "VERIFY_X509_STRICT", None)
+    if strict is None:  # pragma: no cover - depends on the linked OpenSSL build
+        return
+    ctx.verify_flags |= strict
+
+
+def validate_tls_ciphers(value: str) -> str:
+    """Validate an operator OpenSSL cipher string, rejecting non-forward-secret key exchange.
+
+    Returns ``value`` unchanged when it parses and every resolved TLS 1.2 suite uses (EC)DHE (TLS 1.3
+    suites are inherently ECDHE + AEAD). Raises ``ValueError`` — surfaced as a config-load error — for
+    an unparseable string or one that would admit a static-RSA/DH key exchange, closing the 11.6.2 gap
+    that a misconfigured ``tls_ciphers`` could widen the key exchange below policy."""
+    probe = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    try:
+        probe.set_ciphers(value)
+    except ssl.SSLError as exc:
+        raise ValueError(f"tls_ciphers is not a valid OpenSSL cipher string: {exc}") from exc
+    non_fs = sorted(
+        {str(c.get("name", "?")) for c in probe.get_ciphers() if not _is_forward_secret(c)}
+    )
+    if non_fs:
+        raise ValueError(
+            "tls_ciphers must resolve to forward-secret (EC)DHE suites only (ASVS 11.6.2); "
+            f"these admit a non-forward-secret key exchange: {', '.join(non_fs)}"
+        )
+    return value
+
+
+def _is_forward_secret(cipher: Mapping[str, object]) -> bool:
+    """Whether a ``SSLContext.get_ciphers()`` entry uses an (EC)DHE — forward-secret — key exchange."""
+    name = str(cipher.get("name", ""))
+    # TLS 1.3 suite names (TLS_AES_*, TLS_CHACHA20_*) are always ECDHE and cannot be configured down.
+    if name.startswith("TLS_") or cipher.get("protocol") == "TLSv1.3":
+        return True
+    if name.startswith(("ECDHE", "DHE")):
+        return True
+    # Fall back to the human description's Kx token (stable across CPython versions).
+    desc = str(cipher.get("description", ""))
+    return "Kx=ECDH" in desc or "Kx=DH" in desc