messagefoundry-webconsole 0.2.15__py3-none-any.whl

messagefoundry_webconsole/routes/monitoring.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""L1a: read-only monitoring pages (alerts + event log)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, FastAPI, Query, Request
+from fastapi.responses import HTMLResponse
+
+from messagefoundry.api._ui_seam import UiDeps
+from messagefoundry.auth import Identity, Permission
+
+from .. import pages
+from .._auth import (
+    require_ui,
+)
+
+
+def register(app: FastAPI, deps: UiDeps) -> None:
+    """L1a: read-only monitoring pages (alerts + event log). Reuses the metadata-only JSON
+    handlers (no PHI, no step-up) — ADR 0065, BACKLOG #75 phase 1."""
+    core = deps.core
+
+    @app.get("/ui/alerts", response_class=HTMLResponse)
+    async def ui_alerts(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(
+            require_ui(Permission.MONITORING_READ, Permission.MONITORING_DIAGNOSE)
+        ),
+    ) -> HTMLResponse:
+        # Active instances need monitoring:diagnose, rules need monitoring:read — the page
+        # requires BOTH (fail-closed), then calls the handlers directly (their own gates are
+        # skipped, so require_ui re-asserts the permissions the same way the other /ui routes do).
+        # Pass every param explicitly: calling the handler directly (not via Depends) leaves
+        # its Query(...) defaults unresolved, so limit must be a real int here.
+        instances = await core.list_active_alerts(engine=engine, identity=identity, limit=200)
+        config = await core.alerts_rules(request, _user=identity)
+        return HTMLResponse(pages.alerts(instances, config))
+
+    @app.get("/ui/events", response_class=HTMLResponse)
+    async def ui_events(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_READ)),
+        connection: str | None = Query(None, max_length=256),
+        kind: str | None = Query(None, max_length=64),
+    ) -> HTMLResponse:
+        # L6b (#75 parity): expose the JSON handler's event-kind filter (a single kind from
+        # the fixed dropdown → a one-element kinds list; blank/unknown = no filter).
+        kinds = [kind] if kind else None
+        rows = await core.list_connection_events(
+            engine=engine,
+            identity=identity,
+            connection=connection,
+            kind=kinds,
+            since=None,
+            limit=100,
+            request=request,
+        )
+        return HTMLResponse(pages.events(rows, connection=connection or "", kind=kind or ""))
+
+    async def _flow_data(request: Request, engine: Any, identity: Identity) -> tuple[Any, Any]:
+        """Fetch the two read-only monitoring:read sources for the Flow & trends page (BACKLOG #76):
+        the status-colored graph (from the Registry edges) + the metrics-history ring. Their own
+        ``Depends`` gates are skipped on a direct call, so ``require_ui`` re-asserted the permission."""
+        graph = await core.graph_edges(engine=engine, identity=identity)
+        history = await core.metrics_history(request, _user=identity)
+        return graph, history
+
+    @app.get("/ui/monitoring", response_class=HTMLResponse)
+    async def ui_monitoring(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_READ)),
+    ) -> HTMLResponse:
+        # #76: the status-colored by-name data-flow graph + the historical queue-trend chart, both
+        # inline SVG (CSP script-src 'self'). Read-only, metadata only — no message body.
+        graph, history = await _flow_data(request, engine, identity)
+        return HTMLResponse(pages.flow_and_trends(graph, history))
+
+    @app.get("/ui/monitoring/live", response_class=HTMLResponse)
+    async def ui_monitoring_live(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        # activity=False (ASVS 14.3.1): the Flow page's auto-refresh is timer-driven, not user activity.
+        identity: Identity = Depends(require_ui(Permission.MONITORING_READ, activity=False)),
+    ) -> HTMLResponse:
+        # The poll target app.js swaps into the page's [data-mf-fragment] container (server-rendered,
+        # already-escaped) so the graph's live status colours + the trend refresh without a WebSocket.
+        graph, history = await _flow_data(request, engine, identity)
+        return HTMLResponse(pages.flow_and_trends_fragment(graph, history))

messagefoundry_webconsole/routes/monitoring_writes.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""L3a: monitoring write actions (alert ack/resolve, statistics reset, integrity check, DR activate/release)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from urllib.parse import parse_qsl
+
+from fastapi import Depends, FastAPI, Request, Response
+from fastapi.responses import HTMLResponse, RedirectResponse
+from pydantic import ValidationError
+
+from messagefoundry.api._ui_seam import UiDeps
+from messagefoundry.api.models import (
+    AlertSuspendRequest,
+    StatsResetRequest,
+    StatsResetTarget,
+)
+from messagefoundry.auth import Identity, Permission
+
+from .. import pages
+from .._auth import (
+    assert_same_origin,
+    require_ui,
+)
+
+
+def register(app: FastAPI, deps: UiDeps) -> None:
+    """L3a: monitoring write actions (alert ack/resolve, statistics reset, DB integrity check,
+    DR activate/release). Permission-gated to MATCH the JSON handlers (no step-up — they are not
+    require_step_up), CSRF-guarded by assert_same_origin, each redirecting back to its page.
+
+    These deliberately do NOT call register_ui_action(): that registry only gates the
+    step-up re-auth AUTO-RETRY allow-list (is_safe_ui_action), and these use plain require_ui —
+    they never route through /ui/reauth, so they have nothing to register."""
+    core = deps.core
+
+    @app.post("/ui/alerts/{alert_id}/ack")
+    async def ui_ack_alert(
+        alert_id: int,
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        assert_same_origin(request)
+        await core.ack_alert(alert_id, engine=engine, identity=identity, request=request)
+        return RedirectResponse("/ui/alerts", status_code=303)
+
+    @app.post("/ui/alerts/{alert_id}/resolve")
+    async def ui_resolve_alert(
+        alert_id: int,
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        assert_same_origin(request)
+        await core.resolve_alert(alert_id, request=request, engine=engine, identity=identity)
+        return RedirectResponse("/ui/alerts", status_code=303)
+
+    @app.post("/ui/alerts/{alert_id}/suspend")
+    async def ui_suspend_alert(
+        alert_id: int,
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        # #143 windowed suspend: the mute duration arrives as a `minutes` hidden/select form field; build
+        # the typed request and reuse the single audited JSON handler (scope check + store + notifier cache
+        # + audit). An out-of-range/undecodable value falls back to 60 minutes; core 404s an unknown id.
+        assert_same_origin(request)
+        form = dict(parse_qsl((await request.body()).decode("utf-8", "replace")))
+        try:
+            body = AlertSuspendRequest(minutes=float(form.get("minutes") or "60"))
+        except (ValueError, ValidationError):
+            body = AlertSuspendRequest(minutes=60.0)
+        await core.suspend_alert(
+            alert_id, body=body, request=request, engine=engine, identity=identity
+        )
+        return RedirectResponse("/ui/alerts", status_code=303)
+
+    @app.post("/ui/alerts/{alert_id}/resume")
+    async def ui_resume_alert(
+        alert_id: int,
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        assert_same_origin(request)
+        await core.resume_alert(alert_id, request=request, engine=engine, identity=identity)
+        return RedirectResponse("/ui/alerts", status_code=303)
+
+    @app.post("/ui/statistics/reset")
+    async def ui_reset_statistics(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        assert_same_origin(request)
+        # The status-page "Reset statistics" button zeroes ALL cumulative counters.
+        await core.reset_statistics(
+            StatsResetRequest(all=True), engine=engine, identity=identity, request=request
+        )
+        return RedirectResponse("/ui/status", status_code=303)
+
+    @app.post("/ui/statistics/reset-one")
+    async def ui_reset_statistics_one(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        # L6b (#75 parity): reset ONE connection's counters from its dashboard row (the
+        # desktop's per-row/selected reset). role/channel_id/destination arrive as hidden
+        # form fields (names aren't path-safe); build a single-target request. The finer
+        # per-channel scope check runs inside core.reset_statistics (403 for an out-of-scope
+        # user), exactly like the reset-all path.
+        assert_same_origin(request)
+        form = dict(parse_qsl((await request.body()).decode("utf-8", "replace")))
+        role: Literal["source", "destination"]
+        if form.get("role") == "source":
+            role = "source"
+        elif form.get("role") == "destination":
+            role = "destination"
+        else:
+            return RedirectResponse("/ui", status_code=303)
+        channel_id = form.get("channel_id", "")
+        destination = form.get("destination") or None
+        if not channel_id:
+            return RedirectResponse("/ui", status_code=303)
+        try:
+            target = StatsResetTarget(role=role, channel_id=channel_id, destination=destination)
+        except ValidationError:
+            return RedirectResponse("/ui", status_code=303)
+        await core.reset_statistics(
+            StatsResetRequest(targets=[target]), engine=engine, identity=identity, request=request
+        )
+        return RedirectResponse("/ui", status_code=303)
+
+    @app.post("/ui/statistics/reset-many")
+    async def ui_reset_statistics_many(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> Response:
+        # Bulk counter reset over a selection of dashboard rows (both roles). Each `sel` is an
+        # encoded _row_key (role|b64url(channel_id)|b64url(destination)); build ONE
+        # StatsResetRequest and call reset_statistics directly — its per-channel scope check runs
+        # per target (a single out-of-scope target 403s the batch, matching reset-one). Undecodable
+        # sels are dropped (never reflected). require_ui already re-asserted MONITORING_DIAGNOSE.
+        assert_same_origin(request)
+        pairs = parse_qsl((await request.body()).decode("utf-8", "replace"))
+        targets: list[StatsResetTarget] = []
+        seen: set[tuple[str, str, str]] = set()
+        for key, value in pairs:
+            if key != "sel":
+                continue
+            decoded = pages.decode_row_key(value)
+            if decoded is None or decoded in seen:
+                continue
+            seen.add(decoded)
+            role, channel_id, destination = decoded
+            try:
+                targets.append(
+                    StatsResetTarget(
+                        role=role,
+                        channel_id=channel_id,
+                        destination=destination or None,
+                    )
+                )
+            except ValidationError:
+                continue
+        await core.reset_statistics(
+            StatsResetRequest(targets=targets), engine=engine, identity=identity, request=request
+        )
+        return RedirectResponse("/ui", status_code=303)
+
+    @app.post("/ui/status/integrity-check")
+    async def ui_integrity_check(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MONITORING_DIAGNOSE)),
+    ) -> HTMLResponse:
+        assert_same_origin(request)
+        result = await core.integrity_check(engine=engine, _user=identity)
+        return HTMLResponse(pages.integrity_result(result))
+
+    @app.post("/ui/dr/activate")
+    async def ui_dr_activate(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.DR_OPERATE)),
+    ) -> Response:
+        assert_same_origin(request)
+        await core.dr_activate(engine=engine, identity=identity, body=None)
+        return RedirectResponse("/ui/status", status_code=303)
+
+    @app.post("/ui/dr/release")
+    async def ui_dr_release(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.DR_OPERATE)),
+    ) -> Response:
+        assert_same_origin(request)
+        await core.dr_release(engine=engine, identity=identity)
+        return RedirectResponse("/ui/status", status_code=303)

messagefoundry_webconsole/routes/oidc.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""W4-5 (ADR 0142): the browser federated-login legs — OIDC authorization-code + PKCE, default-OFF.
+
+Two GET routes, both unauthenticated, modelled closely on ``routes/sso.py``:
+
+* ``/ui/oidc/start`` mints a server-side flow, drops an opaque flow id in a short-lived ``__Host-``
+  cookie, and 303s the browser to the IdP.
+* ``/ui/oidc/callback`` re-binds cookie + ``state``, redeems the code, and lands the session.
+
+**Registration is self-gating.** ``register`` returns before declaring either route unless
+``[auth].oidc_enabled`` is set, so with federation off the two paths are not in the route table at all
+and ``tests/golden/ui_routes.txt`` is unchanged — that unchanged golden IS the AC-1 proof.
+
+Two deliberate departures a reviewer will want to check rather than "fix":
+
+* **No same-origin assertion on either leg.** ``assert_same_origin`` rejects any request whose
+  ``Sec-Fetch-Site`` is ``cross-site``, and the IdP's redirect back here is *legitimately* a top-level
+  cross-site navigation. Adding it would 403 every real federated login while every hermetic test
+  still passed (test clients send no ``Sec-Fetch`` headers). ``routes/sso.py`` does not call it either.
+* **The callback returns 200 + a meta refresh, never a 303.** See :func:`pages.oidc_landing`.
+
+Ordering rule inherited from ``sso.py``: **every audit-writing branch sits behind the rate limiter.**
+Both legs are unauthenticated, so an attacker looping them would otherwise be an unbounded
+audit_log-write amplifier. The availability and rate-limit rejects therefore write no audit row.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Query, Request, Response
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from messagefoundry.api._ui_seam import UiDeps
+from messagefoundry.api.security import get_auth
+from messagefoundry.auth.oidc import FlowCacheFullError, FlowError
+
+from .. import pages
+from .._auth import (
+    clear_oidc_flow_cookie,
+    oidc_flow_cookie_name,
+    set_oidc_flow_cookie,
+    set_session_cookie,
+)
+
+_log = logging.getLogger(__name__)
+
+#: Service-side reject reasons mapped to the login page's allow-listed short codes. Anything not in
+#: here collapses to ``oidc_failed`` — an unrecognised slug must never become a reflected error code.
+_REASON_TO_CODE = {
+    "state_unknown": "flow_binding_missing",
+    "state_mismatch": "flow_binding_missing",
+    "mfa_claim_missing": "sso_mfa_required",
+}
+
+
+def _fail(request: Request, code: str) -> Response:
+    """A terminal callback failure: 303 to the login page AND clear the single-use flow cookie."""
+    resp = RedirectResponse(f"/ui/login?e={code}", status_code=303)
+    clear_oidc_flow_cookie(resp, request)
+    return resp
+
+
+def register(app: FastAPI, deps: UiDeps) -> None:
+    """Register the federated-login legs — ONLY when ``[auth].oidc_enabled`` is set.
+
+    The gate reads ``deps.oidc_enabled`` (static CONFIG), not ``oidc_available`` (the advisory,
+    non-sticky runtime health flag): the route table is fixed at app construction, and gating it on a
+    value that changes when an IdP blips would make the surface appear and disappear across restarts.
+
+    It also must NOT read ``app.state.auth``. Under ``messagefoundry serve`` the app is built by
+    ``create_managed_app``, which attaches the AuthService inside the **lifespan** — long after
+    ``mount_ui`` has fixed the route table — so an ``app.state.auth`` gate registers nothing in
+    production while passing every test that constructs the app with ``auth=`` directly.
+    """
+    if not deps.oidc_enabled:
+        return
+
+    @app.get("/ui/oidc/start")
+    async def ui_oidc_start(request: Request) -> Response:
+        auth = get_auth(request)
+        if auth is None or not auth.oidc_enabled:
+            # Disabled: redirect WITHOUT auditing — the sso.py anti-flood carve-out. Note this reads
+            # oidc_enabled, not oidc_available: AC-8 requires recovery without an engine restart, so
+            # the start leg ALWAYS attempts and a degraded IdP is discovered per-request.
+            return RedirectResponse("/ui/login?e=oidc_unavailable", status_code=303)
+        client = request.client.host if request.client else None
+        if not auth.allow_login_attempt(client):
+            # A _log.warning, never an audit — parity with sso.py, so exhaustion writes zero DB rows.
+            _log.warning("federated sign-in rate limit exceeded for %s", client or "<unknown>")
+            return RedirectResponse("/ui/login?e=rate_limited", status_code=303)
+        mode = request.headers.get("Sec-Fetch-Mode")
+        if mode is not None and mode != "navigate":
+            # A non-navigation fetch of a login leg is drive-by probing. Audited (behind the limiter).
+            await auth.audit_oidc_reject("non_navigation_fetch")
+            return RedirectResponse("/ui/login?e=oidc_failed", status_code=303)
+        public_origin = getattr(request.app.state, "public_origin", None)
+        if not public_origin:
+            # The redirect_uri is derived from public_origin, never from the Host header — a
+            # client-forwardable Host would let an attacker steer where the IdP sends the code.
+            _log.warning("federated sign-in unavailable: [api].public_origin is not set")
+            return RedirectResponse("/ui/login?e=oidc_unavailable", status_code=303)
+        try:
+            flow_id, authorization_url = await auth.begin_oidc_login(
+                client=client, public_origin=public_origin
+            )
+        except FlowCacheFullError:
+            # The bounded flow cache REJECTS rather than evicts (evict-oldest would make a start-leg
+            # flood a login DoS). That is a flood signal, so it is logged, not audited per request.
+            _log.warning("federated flow cache is full; refusing new sign-in for %s", client or "?")
+            return RedirectResponse("/ui/login?e=rate_limited", status_code=303)
+        except FlowError:
+            await auth.audit_oidc_reject("start_failed")
+            return RedirectResponse("/ui/login?e=oidc_failed", status_code=303)
+        resp = RedirectResponse(authorization_url, status_code=303)
+        set_oidc_flow_cookie(resp, flow_id, request=request, max_age=auth.oidc_flow_ttl_seconds)
+        return resp
+
+    @app.get("/ui/oidc/callback")
+    async def ui_oidc_callback(
+        request: Request,
+        code: str | None = Query(None, max_length=4096),
+        state: str | None = Query(None, max_length=512),
+        error: str | None = Query(None, max_length=64),
+    ) -> Response:
+        # `error_description` is deliberately NOT accepted: it is free-form IdP/attacker text, and the
+        # bounded lengths above let FastAPI reject an oversized query string before any handler runs.
+        auth = get_auth(request)
+        if auth is None or not auth.oidc_enabled:
+            return RedirectResponse("/ui/login?e=oidc_unavailable", status_code=303)
+        client = request.client.host if request.client else None
+        if not auth.allow_login_attempt(client):
+            # The limiter runs on BOTH legs (ADR 0142): the callback is equally unauthenticated.
+            _log.warning("federated callback rate limit exceeded for %s", client or "<unknown>")
+            return RedirectResponse("/ui/login?e=rate_limited", status_code=303)
+        mode = request.headers.get("Sec-Fetch-Mode")
+        if mode is not None and mode != "navigate":
+            await auth.audit_oidc_reject("non_navigation_fetch")
+            return _fail(request, "oidc_failed")
+        # NOTE: no assert_same_origin here. Sec-Fetch-Site on this leg is legitimately "cross-site".
+
+        flow_id = request.cookies.get(oidc_flow_cookie_name(request))
+        if not flow_id:
+            # AC-7: without the browser-binding cookie the request is refused even when state and
+            # code are otherwise valid — server-side `state` alone would let whoever presents a valid
+            # (state, code) pair have the session minted into THEIR browser.
+            await auth.audit_oidc_reject("flow_binding_missing")
+            return _fail(request, "flow_binding_missing")
+        if error is not None:
+            # The IdP reported a failure. Audit a fixed slug; never the IdP's own string.
+            await auth.audit_oidc_reject("idp_error")
+            return _fail(request, "oidc_failed")
+        if not code or not state:
+            await auth.audit_oidc_reject("malformed_callback")
+            return _fail(request, "oidc_failed")
+
+        outcome = await auth.complete_oidc_login(
+            flow_id=flow_id,
+            state=state,
+            code=code,
+            client=client,
+            public_origin=getattr(request.app.state, "public_origin", "") or "",
+        )
+        if not outcome.ok or outcome.token is None:
+            # complete_oidc_login already audited the closed-set reason; map it to an allow-listed
+            # short code, defaulting to the generic one so an unrecognised slug is never reflected.
+            return _fail(request, _REASON_TO_CODE.get(outcome.reason or "", "oidc_failed"))
+        resp = HTMLResponse(pages.oidc_landing(), status_code=200)
+        set_session_cookie(resp, outcome.token, request=request)
+        clear_oidc_flow_cookie(resp, request)
+        return resp

messagefoundry_webconsole/routes/search.py

@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""content-search: a step-up-unlock GET page over the JSON search_messages handler (ADR 0046 #51),
+plus saved / layered filter presets (BACKLOG #151, ADR 0136)."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+from fastapi import Depends, FastAPI, HTTPException, Query, Request
+from fastapi.responses import HTMLResponse, RedirectResponse, Response
+
+from messagefoundry.api._ui_seam import UiDeps
+from messagefoundry.api.models import SearchPresetCreateRequest, SearchPresetCriteria
+from messagefoundry.auth import Identity, Permission
+
+from .. import pages
+from .._auth import (
+    assert_same_origin,
+    register_ui_action,
+    require_ui,
+    require_ui_step_up,
+)
+from ._common import _form_pairs
+
+# content-search (ADR 0046 #51): the search PAGE is step-up-gated (bulk-PHI decrypt), so register
+# it as an UNLOCK form — a stale step-up 303s to /ui/reauth and GET-redirects back to the fresh
+# search form (the L0c step-up-to-unlock primitive; the PHI-shaped search term is a GET query, so
+# it is deliberately NOT carried across the redirect — the operator re-enters it in the window).
+register_ui_action(
+    r"^/ui/messages/search$", Permission.MESSAGES_READ, auto_retry=False, unlock=True
+)
+# The layered run (ADR 0136) is likewise a step-up-gated GET that composes + decrypts; register it as
+# an UNLOCK form too. Its query carries only preset IDS (never the PHI needle — that's server-composed
+# from the encrypted column), so the deliberate-drop posture is preserved.
+register_ui_action(
+    r"^/ui/messages/search/layered$", Permission.MESSAGES_READ, auto_retry=False, unlock=True
+)
+
+
+def register(app: FastAPI, deps: UiDeps) -> None:
+    """content-search + saved/layered presets over the JSON handlers (ADR 0046 / 0136)."""
+    core = deps.core
+
+    async def _presets(engine: Any, identity: Identity, request: Request) -> list[Any]:
+        return list(
+            (
+                await core.list_search_presets(engine=engine, identity=identity, request=request)
+            ).presets
+        )
+
+    @app.get("/ui/messages/search", response_class=HTMLResponse)
+    async def ui_message_search(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui_step_up(Permission.MESSAGES_READ)),
+        content: str | None = Query(None, max_length=512),
+        field_path: str | None = Query(None, max_length=32),
+        field_value: str | None = Query(None, max_length=512),
+        target: str = Query("both", pattern="^(raw|summary|both)$"),
+        channel_id: str | None = Query(None, max_length=256),
+        status_filter: str | None = Query(None, alias="status", max_length=64),
+        message_type: str | None = Query(None, max_length=64),
+        control_id: str | None = Query(None, max_length=256),
+        limit: int = Query(50, ge=1, le=500),
+    ) -> HTMLResponse:
+        # A criterion is required to search; with none, render the bare form (no decrypt/audit).
+        # A field_path alone is a valid presence-test search (matches make_spec/row_matches),
+        # so it counts as a criterion too — keeping /ui at parity with the JSON API.
+        has_criteria = bool(content) or bool(field_value) or bool(field_path)
+        preset_list = await _presets(engine, identity, request)
+        shared = dict(  # noqa: C408
+            content=content or "",
+            field_path=field_path or "",
+            field_value=field_value or "",
+            target=target,
+            channel_id=channel_id or "",
+            status=status_filter or "",
+            message_type=message_type or "",
+            control_id=control_id or "",
+        )
+        if not has_criteria:
+            return HTMLResponse(pages.message_search(None, presets=preset_list, **shared))
+        try:
+            # Call the JSON handler directly (its require_step_up Depends is skipped —
+            # require_ui_step_up above re-asserted it); pass every param explicitly.
+            results = await core.search_messages(
+                request,
+                engine=engine,
+                identity=identity,
+                content=content,
+                field_path=field_path,
+                field_value=field_value,
+                target=target,
+                channel_id=channel_id,
+                status=status_filter,
+                message_type=message_type,
+                control_id=control_id,
+                limit=limit,
+                scan_limit=deps.default_scan_limit,
+            )
+        except HTTPException as exc:
+            if exc.status_code == 400:  # make_spec rejected the criteria — re-render the form
+                return HTMLResponse(
+                    pages.message_search(
+                        None, error=str(exc.detail), presets=preset_list, **shared
+                    ),
+                    status_code=400,
+                )
+            raise
+        return HTMLResponse(pages.message_search(results, presets=preset_list, **shared))
+
+    @app.post("/ui/messages/search/presets")
+    async def ui_save_preset(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui_step_up(Permission.MESSAGES_READ)),
+    ) -> Response:
+        # Same-origin; step-up (persists a possibly-PHI criteria). Body-carrying, so it re-opens via the
+        # search page's unlock form on a stale step-up rather than being auto-retried.
+        assert_same_origin(request)
+        form = dict(await _form_pairs(request))
+        criteria = SearchPresetCriteria(
+            content=form.get("content") or None,
+            field_path=form.get("field_path") or None,
+            field_value=form.get("field_value") or None,
+            target=form.get("target")
+            if form.get("target") in ("raw", "summary", "both")
+            else "both",  # type: ignore[arg-type]
+            channel_id=form.get("channel_id") or None,
+            status=form.get("status") or None,
+            message_type=form.get("message_type") or None,
+            control_id=form.get("control_id") or None,
+            limit=50,
+        )
+        try:
+            body = SearchPresetCreateRequest(name=form.get("name", ""), criteria=criteria)
+            await core.create_search_preset(
+                body=body, engine=engine, identity=identity, request=request
+            )
+        except HTTPException as exc:
+            preset_list = await _presets(engine, identity, request)
+            return HTMLResponse(
+                pages.message_search(None, error=str(exc.detail), presets=preset_list),
+                status_code=exc.status_code,
+            )
+        except ValueError:  # pydantic validation (e.g. empty name)
+            preset_list = await _presets(engine, identity, request)
+            return HTMLResponse(
+                pages.message_search(None, error="a preset name is required", presets=preset_list),
+                status_code=400,
+            )
+        return RedirectResponse("/ui/messages/search", status_code=303)
+
+    @app.post("/ui/messages/search/presets/{preset_id}/delete")
+    async def ui_delete_preset(
+        preset_id: str,
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui(Permission.MESSAGES_READ)),
+    ) -> Response:
+        # Deleting your own preset is low-risk metadata (no step-up); same-origin CSRF guard.
+        assert_same_origin(request)
+        # A missing preset (already deleted) → the redirect just re-renders the list.
+        with contextlib.suppress(HTTPException):
+            await core.delete_search_preset(
+                preset_id, engine=engine, identity=identity, request=request
+            )
+        return RedirectResponse("/ui/messages/search", status_code=303)
+
+    @app.get("/ui/messages/search/layered", response_class=HTMLResponse)
+    async def ui_layered_search(
+        request: Request,
+        engine: Any = Depends(deps.get_engine),
+        identity: Identity = Depends(require_ui_step_up(Permission.MESSAGES_READ)),
+        presets: list[str] | None = Query(None),
+    ) -> HTMLResponse:
+        preset_list = await _presets(engine, identity, request)
+        ids = ",".join(p for p in (presets or []) if p)
+        if not ids:
+            return HTMLResponse(
+                pages.message_search(
+                    None, error="select at least one preset to layer", presets=preset_list
+                ),
+                status_code=400,
+            )
+        try:
+            results = await core.layered_search(
+                request,
+                engine=engine,
+                identity=identity,
+                presets=ids,
+                limit=50,
+                scan_limit=deps.default_scan_limit,
+            )
+        except HTTPException as exc:
+            if exc.status_code in (400, 404):
+                return HTMLResponse(
+                    pages.message_search(None, error=str(exc.detail), presets=preset_list),
+                    status_code=exc.status_code,
+                )
+            raise
+        return HTMLResponse(pages.message_search(results, presets=preset_list))