messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/console/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""PySide6 admin console for MessageFoundry.
+
+A thin desktop client over the localhost API (:mod:`messagefoundry.api`): a channel
+dashboard (start/stop), a message browser with an HL7 parse-tree viewer and delivery/
+audit trail, and replay. The console never touches the store or engine directly — it
+speaks only HTTP, so the same UI drives in-process, local-daemon, and (later) remote
+engines.
+
+The API client (:mod:`.client`) is independent of Qt and unit-testable on its own; the
+widgets (:mod:`.widgets`) are imported lazily so importing this package doesn't require
+PySide6 unless you actually open the GUI.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.console.client import ApiError, EngineClient
+
+__all__ = ["EngineClient", "ApiError"]

messagefoundry/console/__main__.py

@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Console entrypoint:  python -m messagefoundry.console [--url URL]
+
+Connects to a running engine API (default http://127.0.0.1:8765 — start one with
+``python -m messagefoundry serve``), opens the admin window, and auto-refreshes channel and
+message state on a timer. The interval is user-selectable from the window (link → dialog) and
+remembered across runs (QSettings); ``--poll`` is just the default for a first run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from PySide6.QtCore import QSettings
+from PySide6.QtWidgets import QApplication, QDialog
+
+from messagefoundry.console.change_password import ChangePasswordDialog
+from messagefoundry.console.client import ApiError, EngineClient
+from messagefoundry.console.login import LoginDialog
+from messagefoundry.console.mfa import MfaVerifyDialog, make_mfa_handler
+from messagefoundry.console.reauth import make_step_up_handler
+from messagefoundry.console.shell import AppWindow
+
+log = logging.getLogger(__name__)
+
+_SETTINGS_KEY = "autorefresh/seconds"
+_DEFAULT_SIZE = (2560, 1440)
+# The cached token is a PHI-scoped bearer credential (the user's full RBAC, incl. messages:view_raw)
+# valid for the server-side session lifetime. It lives in the OS keyring (Windows Credential
+# Manager) and is re-validated against /auth/me on startup, so a stale/revoked one is discarded.
+_KEYRING_SERVICE = "MessageFoundry"
+
+
+def _load_token(base_url: str) -> str | None:
+    try:
+        import keyring
+        from keyring.errors import KeyringError
+    except ImportError:
+        return None
+    try:
+        return keyring.get_password(_KEYRING_SERVICE, base_url)
+    except KeyringError as exc:  # keyring present but locked/unavailable — fall back to sign-in
+        log.warning("could not read stored credential: %s", exc)
+        return None
+
+
+def _save_token(base_url: str, token: str) -> None:
+    try:
+        import keyring
+        from keyring.errors import KeyringError
+    except ImportError:
+        return  # no keyring backend — the session simply isn't remembered across launches
+    try:
+        keyring.set_password(_KEYRING_SERVICE, base_url, token)
+    except KeyringError as exc:
+        log.warning("could not store credential (will re-prompt next launch): %s", exc)
+
+
+def _delete_token(base_url: str) -> bool:
+    """Clear the stored token. Returns False if it may still be present (CONSOLE-2)."""
+    try:
+        import keyring
+        from keyring.errors import KeyringError, PasswordDeleteError
+    except ImportError:
+        return True  # nothing was persisted to begin with
+    try:
+        keyring.delete_password(_KEYRING_SERVICE, base_url)
+        return True
+    except PasswordDeleteError:
+        return True  # no such entry — already absent, effectively cleared
+    except KeyringError as exc:
+        log.warning("could not clear stored credential — it may still be present: %s", exc)
+        return False
+
+
+def _authenticate(client: EngineClient) -> bool:
+    """Ensure the client is authenticated when the engine requires it.
+
+    Returns True to proceed (authenticated, or auth disabled, or unreachable so the window can show
+    the connection error), or False if the user cancelled the sign-in dialog.
+    """
+    try:
+        client.providers()  # 200 when auth is on; 503 when disabled
+    except ApiError as exc:
+        if exc.status == 503 or exc.status is None:
+            return True  # auth disabled, or unreachable (the window surfaces the error)
+    stored = _load_token(client.base_url)
+    if stored:
+        try:
+            client.set_token(stored)
+            return True
+        except ApiError:
+            client.clear_auth()
+            _delete_token(client.base_url)
+    while True:
+        login = LoginDialog(client)
+        if login.exec() != QDialog.DialogCode.Accepted:
+            return False
+        if not login.must_change_password:
+            # A second factor is required (WP-14): prompt for the TOTP / recovery code now. If the
+            # user cancels, REVOKE the un-MFA'd session server-side (not just locally) — the login
+            # already minted a durable session row, so a bare clear_auth() would leave it alive until
+            # expiry. logout() hits /auth/logout to revoke it (mirrors _sign_out); no keyring entry was
+            # saved yet on this branch, so a local clear is the only fallback if the revoke call fails.
+            if login.mfa_required and not _verify_mfa(client):
+                try:
+                    client.logout()
+                except ApiError as exc:
+                    log.warning("server-side logout after MFA cancel failed: %s", exc)
+                    client.clear_auth()
+                continue
+            break
+        # Forced change: the session is must-change-restricted (403 on protected routes). Let the
+        # user set a new password, prefilling the current one they just typed and the server
+        # accepted.
+        change = ChangePasswordDialog(client, current_password=login.entered_password)
+        login.entered_password = ""  # nosec B105 (clears the plaintext seam, not a credential; M4)
+        if change.exec() != QDialog.DialogCode.Accepted:
+            client.clear_auth()  # drop the restricted token; the user bailed out
+            continue  # back to sign-in (still blocked until they change it)
+        # change_password() already revoked + cleared the session server-side, so the loop falls
+        # through to a fresh sign-in with the new password rather than admitting the dead token.
+    if client.token is not None:
+        _save_token(client.base_url, client.token)
+    return True
+
+
+def _verify_mfa(client: EngineClient) -> bool:
+    """Prompt for a second factor after a login that reported ``mfa_required`` (WP-14). Returns True
+    iff the TOTP / recovery code verified."""
+    return MfaVerifyDialog(client).exec() == QDialog.DialogCode.Accepted
+
+
+def _sign_out(client: EngineClient, app: QApplication) -> None:
+    base_url = client.base_url
+    try:
+        client.logout()  # revoke the session server-side
+    except ApiError as exc:
+        log.warning("server-side logout failed: %s", exc)
+    if not _delete_token(base_url):
+        log.warning("local credential may not have been cleared; remove it from the OS keyring")
+    app.quit()  # re-launch the console to sign in again
+
+
+def _password_changed(client: EngineClient, app: QApplication) -> None:
+    """Route back to sign-in after an in-app password change.
+
+    The dialog already called ``change_password`` (server revoked the session, client cleared its
+    token), so this only clears the cached keyring credential and quits — relaunch lands on the
+    sign-in dialog where the user authenticates with the new password.
+    """
+    if not _delete_token(client.base_url):
+        log.warning("local credential may not have been cleared; remove it from the OS keyring")
+    app.quit()  # re-launch the console to sign in with the new password
+
+
+def _session_expired(client: EngineClient, app: QApplication) -> None:
+    """The session expired/was revoked mid-session (a 401 on the health poll). The token is already
+    dead, so just clear the cached credential and quit — re-launch lands on the sign-in dialog (M-26)."""
+    if not _delete_token(client.base_url):
+        log.warning("local credential may not have been cleared; remove it from the OS keyring")
+    app.quit()
+
+
+def _open_window(window: AppWindow, app: QApplication) -> None:
+    """Open at the default size, or maximized if the screen can't fit it.
+
+    ``_DEFAULT_SIZE`` is in physical pixels (what the user sees on a monitor), but Qt's
+    geometry and ``resize()`` are in device-independent (logical) pixels. On a HiDPI display
+    (e.g. a 5K2K monitor at 200% scaling) the two differ by ``devicePixelRatio``, so we compare
+    against the *physical* work area and convert the target back to logical pixels for resize().
+    """
+    target_w, target_h = _DEFAULT_SIZE
+    screen = app.primaryScreen()
+    if screen is None:
+        window.resize(target_w, target_h)
+        window.show()
+        return
+    dpr = screen.devicePixelRatio() or 1.0
+    available = screen.availableGeometry()  # logical pixels
+    if available.width() * dpr < target_w or available.height() * dpr < target_h:
+        window.showMaximized()  # default size is too big for this display
+    else:
+        window.resize(round(target_w / dpr), round(target_h / dpr))
+        window.show()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="messagefoundry.console")
+    parser.add_argument("--url", default="http://127.0.0.1:8765", help="engine API base URL")
+    parser.add_argument("--poll", type=float, default=2.0, help="default auto-refresh seconds")
+    parser.add_argument(
+        "--service-name", default="MessageFoundry", help="Windows service name for the Status page"
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="allow plaintext http to a non-loopback engine (trusted-network dev only; no TLS yet)",
+    )
+    parser.add_argument(
+        "--client-cert",
+        default=None,
+        help="PEM client certificate to present for mutual TLS (ASVS 12.3.5; opt-in, https only)",
+    )
+    parser.add_argument(
+        "--client-key",
+        default=None,
+        help="private key for --client-cert, when it is not bundled in the cert PEM",
+    )
+    args = parser.parse_args(argv)
+
+    app = QApplication(sys.argv[:1])
+    app.setOrganizationName("MessageFoundry")
+    app.setApplicationName("Console")
+
+    try:
+        client = EngineClient(
+            args.url,
+            allow_insecure=args.insecure,
+            tls_client_cert=args.client_cert,
+            tls_client_key=args.client_key,
+        )
+    except ApiError as exc:
+        print(f"error: {exc}", file=sys.stderr)  # e.g. refusing plaintext http to a remote host
+        return 2
+
+    # When the engine demands step-up re-verification on a sensitive action (ASVS 7.5.3), prompt the
+    # operator and retry — instead of surfacing a raw 403 (WP-L3-16, console side).
+    client.set_step_up_handler(make_step_up_handler(client))
+    # And prompt for a second factor when a sensitive op needs one (403 + X-MFA-Required, WP-14).
+    client.set_mfa_handler(make_mfa_handler(client))
+
+    if not _authenticate(client):
+        client.close()
+        return 0
+
+    # A second, read-only client dedicated to background (off-thread) reads — the health poll, the
+    # Engine Status refresh, and the per-page auto-refresh. Keeping those off the primary client
+    # means the handler-bearing, token-mutating primary client is only ever used on the Qt main
+    # thread (sign-in / step-up / MFA / user actions), so no single client is shared across threads.
+    poll_client = client.for_polling()
+
+    # Remembered interval wins; fall back to --poll on first run. QSettings returns the value
+    # as a str (registry) or float (in-memory), so normalise via str() before parsing.
+    settings = QSettings()
+    poll_seconds = float(str(settings.value(_SETTINGS_KEY, args.poll)))
+    window = AppWindow(
+        client, poll_client=poll_client, poll_seconds=poll_seconds, service_name=args.service_name
+    )
+    window.interval_changed.connect(lambda seconds: settings.setValue(_SETTINGS_KEY, seconds))
+    window.logout_requested.connect(lambda: _sign_out(client, app))
+    window.change_password_requested.connect(lambda: _password_changed(client, app))
+    window.session_expired.connect(lambda: _session_expired(client, app))
+
+    # Confirm the engine is reachable before showing a blank window.
+    try:
+        client.health()
+    except ApiError as exc:
+        window._show_error(f"Cannot reach engine: {exc}")  # noqa: SLF001 (entrypoint glue)
+
+    window.refresh_all()
+    _open_window(window, app)
+
+    exit_code = app.exec()
+    client.close()
+    poll_client.close()
+    return int(exit_code)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

messagefoundry/console/_async.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Off-thread API calls for the console.
+
+The :class:`~messagefoundry.console.client.EngineClient` is synchronous, and calling it on the Qt main
+thread freezes the GUI for the duration of the call. That's fine for sub-millisecond loopback reads, but
+a **DB-backed read during a failover** (``/cluster/nodes``, ``/status``) can stall for seconds while the
+new primary recovers — long enough to lock up the window. :class:`AsyncRunner` runs a blocking callable on
+a worker thread and delivers its result (or exception) back to a **main-thread** slot via a queued signal,
+so the handler can safely touch widgets. Background work off the main thread + ``Signal``/``Slot`` back is
+the PySide6 rule (CLAUDE.md §10).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from PySide6.QtCore import QObject, QRunnable, QThreadPool, Signal
+
+
+class _CallSignals(QObject):
+    """Per-call signals — emitted from the worker thread, delivered (queued) on the main thread."""
+
+    done = Signal(object)
+    failed = Signal(object)
+
+
+class _Call(QRunnable):
+    def __init__(self, fn: Callable[[], Any], signals: _CallSignals) -> None:
+        super().__init__()
+        self._fn = fn
+        self._signals = signals
+
+    def run(self) -> None:
+        try:
+            result = self._fn()
+        except Exception as exc:  # noqa: BLE001 — deliver ANY failure to the main thread, never crash the pool worker
+            self._signals.failed.emit(exc)
+        else:
+            self._signals.done.emit(result)
+
+
+class AsyncRunner(QObject):
+    """Run blocking callables off the Qt main thread; deliver the result/error to main-thread slots.
+
+    ``submit(fn, on_done=…, on_error=…)`` runs ``fn()`` on a :class:`QThreadPool` worker; when it finishes,
+    ``on_done(result)`` (or ``on_error(exc)``) fires **on the main thread** so the handler can touch widgets.
+    Call :meth:`stop` on window close: after it, late results are dropped (a slow in-flight call can't update
+    a torn-down widget) and it waits, bounded, for workers to finish.
+
+    Delivery is via the per-call signals connected to **this** runner's bound-method slots. Because the
+    runner is a QObject with main-thread affinity, the cross-thread emit is an AutoConnection that resolves
+    to a *queued* connection — so the callbacks run on the main thread. (Connecting to a bare lambda has no
+    receiver context and would run on the worker thread, so don't.)
+    """
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._pool = QThreadPool(self)
+        self._stopped = False
+        # Hold each call's signals object (and its callbacks) alive until its slot has run: a queued signal
+        # needs its sender to outlive the emit→deliver gap, and the QRunnable is dropped when run() returns.
+        self._calls: dict[
+            _CallSignals, tuple[Callable[[Any], None], Callable[[BaseException], None] | None]
+        ] = {}
+
+    def submit(
+        self,
+        fn: Callable[[], Any],
+        *,
+        on_done: Callable[[Any], None],
+        on_error: Callable[[BaseException], None] | None = None,
+    ) -> None:
+        if self._stopped:
+            return
+        signals = _CallSignals()
+        self._calls[signals] = (on_done, on_error)
+        signals.done.connect(self._handle_done)
+        signals.failed.connect(self._handle_failed)
+        self._pool.start(_Call(fn, signals))
+
+    def _take(self) -> tuple[Callable[[Any], None], Callable[[BaseException], None] | None] | None:
+        sender = self.sender()
+        if not isinstance(sender, _CallSignals):
+            return None
+        return self._calls.pop(sender, None)
+
+    def _handle_done(self, result: Any) -> None:
+        callbacks = self._take()
+        if callbacks is None or self._stopped:
+            return  # dropped after stop(), or an unknown sender — don't touch (torn-down) widgets
+        callbacks[0](result)
+
+    def _handle_failed(self, error: BaseException) -> None:
+        callbacks = self._take()
+        if callbacks is None or self._stopped:
+            return
+        on_error = callbacks[1]
+        if on_error is not None:
+            on_error(error)
+
+    def stop(self) -> None:
+        """Drop late results and wait (bounded) for in-flight workers — call on window/page close."""
+        self._stopped = True
+        self._pool.waitForDone(2000)
+        self._calls.clear()

messagefoundry/console/change_password.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Password-change dialog used both for the forced-change-at-login flow and the in-app
+"Change password…" affordance.
+
+The server (``POST /me/password``) revokes all of the user's sessions on a successful change, so
+:meth:`EngineClient.change_password` clears the client's token afterwards. Callers must therefore
+re-prompt sign-in once this dialog is accepted.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtWidgets import (
+    QDialog,
+    QFormLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from messagefoundry.console.client import ApiError, EngineClient
+from messagefoundry.console.widgets import ERROR_COLOR
+
+
+class ChangePasswordDialog(QDialog):
+    """Collects current/new/confirm passwords and calls :meth:`EngineClient.change_password`.
+
+    ``current_password`` pre-fills (and hides) the current-password field for the forced
+    change-at-login case, where the just-entered plaintext is already known and the server has
+    accepted it. When empty (the in-app affordance), the field is shown so the user types it.
+    Errors are surfaced inline (matching :class:`~messagefoundry.console.login.LoginDialog`):
+    400 carries the server's policy detail, 403 means the current password was wrong.
+    """
+
+    def __init__(
+        self,
+        client: EngineClient,
+        *,
+        current_password: str = "",
+        parent: QWidget | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("Change password — MessageFoundry")
+        self._client = client
+        self._prefilled = bool(current_password)
+
+        self._current = QLineEdit(current_password)
+        self._current.setEchoMode(QLineEdit.EchoMode.Password)
+        self._new = QLineEdit()
+        self._new.setEchoMode(QLineEdit.EchoMode.Password)
+        self._confirm = QLineEdit()
+        self._confirm.setEchoMode(QLineEdit.EchoMode.Password)
+
+        form = QFormLayout()
+        # In the forced-change case the current password is already known/accepted — keep it out of
+        # the form so the user only chooses a new one (it is still sent on submit).
+        if not self._prefilled:
+            form.addRow("Current password", self._current)
+        form.addRow("New password", self._new)
+        form.addRow("Confirm new password", self._confirm)
+
+        self._error = QLabel("")
+        self._error.setStyleSheet(f"color: {ERROR_COLOR};")
+        self._error.setWordWrap(True)
+
+        change = QPushButton("Change password")
+        change.setDefault(True)
+        change.clicked.connect(self._attempt)
+
+        layout = QVBoxLayout(self)
+        layout.addLayout(form)
+        layout.addWidget(self._error)
+        layout.addWidget(change)
+
+        # Enter-key chaining mirrors LoginDialog: walk the visible fields then submit.
+        if not self._prefilled:
+            self._current.returnPressed.connect(self._new.setFocus)
+        self._new.returnPressed.connect(self._confirm.setFocus)
+        self._confirm.returnPressed.connect(self._attempt)
+
+    def _attempt(self) -> None:
+        current = self._current.text()
+        new = self._new.text()
+        confirm = self._confirm.text()
+        if not current or not new or not confirm:
+            self._error.setText("Enter your current password and a new password (twice).")
+            return
+        if new != confirm:
+            self._error.setText("The new passwords do not match.")
+            return
+        try:
+            self._client.change_password(current, new)
+        except ApiError as exc:
+            if exc.status == 403:
+                self._error.setText("Current password is incorrect.")
+            elif exc.status == 400:
+                # The server detail already reads e.g. "password must contain a symbol"; strip the
+                # client's "400: " status prefix so the policy text shows cleanly.
+                self._error.setText(str(exc).removeprefix("400: "))
+            else:
+                self._error.setText(str(exc))
+            return
+        # Clear the plaintext from the fields now the change succeeded — defensive credential
+        # hygiene, since Qt doesn't zero QLineEdit buffers on destruction (L1).
+        for field in (self._current, self._new, self._confirm):
+            field.clear()
+        # change_password() has already cleared the client's token (the server revoked the
+        # session); the caller must re-prompt sign-in.
+        self.accept()