messagefoundry-webconsole 0.2.15__py3-none-any.whl

messagefoundry_webconsole/_security.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Per-response /ui browser-security hardening (ADR 0065 §hardening / BACKLOG #192, ASVS 5.0 L3).
+
+A self-contained, /ui-scoped ASGI middleware the web console installs on the mounted app (in
+:func:`.mount.mount_ui`, before uvicorn serves). It OWNS the browser-security response headers for the
+/ui HTML surface WITHOUT touching the engine (``api/app.py`` is out of this lane's scope):
+
+* a **per-response nonce CSP** — ``script-src 'nonce-<random>' 'strict-dynamic'`` (3.4.7/3.4.8), minted
+  fresh per response and stamped into the ``<script>`` tag via the :mod:`._html` nonce ContextVar so the
+  tag and header always match;
+* **Cross-Origin-Opener-Policy: same-origin** (process isolation) and
+  **Cross-Origin-Resource-Policy: same-origin**;
+* **CSP reporting** — ``report-to``/``report-uri`` pointing at ``POST /ui/csp-report`` plus the modern
+  ``Reporting-Endpoints`` header (3.7.5).
+
+**Secure-context engagement (loopback + effective-https).** All of the above is NEW behavior. It
+engages in an effective-https context (scheme https/wss OR the operator's ``exposure_protected``
+declaration — :func:`._auth.effective_https`, read-only) **OR a loopback secure-context**
+(``http://127.0.0.1`` — a W3C *potentially-trustworthy* origin, signalled by ``app.state.loopback``;
+ADR 0143), and only while the org opt-out (:func:`._auth.browser_hardening_enabled`) is unset — the
+combined gate is :func:`._auth.security_headers_context`. On loopback the http-safe headers (nonce-CSP /
+COOP / CORP / Reporting) engage, but the session cookie's Secure / ``__Host-`` prefix still requires
+real https (:func:`._auth.effective_https`) so login is not broken over cleartext loopback (Chrome /
+Safari reject a Secure / ``__Host-`` cookie over http); HSTS likewise stays off on loopback (the engine
+emits it only over real https / ``exposure_protected``). Where the middleware is a strict no-op — the
+org opt-out, or a cleartext NON-loopback context with no ``exposure_protected`` — it binds no nonce and
+mutates no header, so the engine's existing static ``app.state.ui_csp`` response is emitted
+byte-for-byte. This is why the engine's ``app.state.ui_csp`` seam is left set (option (b) in the lane
+brief): the middleware only OVERRIDES it in a secure context and defers to it otherwise — no per-request
+engine-side switch exists, so the console must own the conditional here.
+
+**Proxy-TLS keying.** This middleware reads ``scope['scheme']`` at the OUTERMOST layer, which precedes
+any inner proxy-headers scheme rewrite. Exactly like the engine's ``_cookie_secure``, a proxy that
+terminates TLS and forwards cleartext to the engine must therefore declare
+``app.state.exposure_protected`` to engage the nonce CSP (a forwarded ``X-Forwarded-Proto=https`` alone
+is NOT seen here). When ``exposure_protected`` is unset in such a deployment the engine's inner static
+self-CSP (``app.state.ui_csp``) remains the floor on every /ui response — the surface is never left
+unprotected, only un-upgraded — so the cookie-and-CSP posture stays consistent with the engine's own
+exposure model rather than diverging from it.
+
+**Middleware ordering.** ``mount_ui`` adds this AFTER the engine's ``@app.middleware("http")``
+security-headers middleware, so Starlette makes it the OUTERMOST layer (``add_middleware`` inserts at
+index 0): on the response path its ``send`` wrapper runs LAST and thus overrides the engine's static CSP
+with the nonce CSP for effective-https /ui responses. It is a PURE ASGI middleware (not
+``BaseHTTPMiddleware``) specifically so the nonce ContextVar it binds before calling downstream
+propagates into the route that renders the page — ``BaseHTTPMiddleware`` runs the endpoint in a detached
+task that a var set inside its own ``dispatch`` would not reach, but a var set by an OUTER pure-ASGI
+middleware before the base layer runs is copied into that task and IS visible.
+
+**Browser-support contract (defined fallback).** These are all defense-in-depth headers a conformant
+modern browser honors; an older client that ignores ``Cross-Origin-Opener-Policy`` /
+``Cross-Origin-Resource-Policy`` / ``Reporting-Endpoints`` / nonce sources / ``SameSite`` simply
+DEGRADES to the prior same-origin posture — the ``SameSite=Strict`` session cookie,
+``frame-ancestors 'none'``, and the ``Sec-Fetch`` / ``Origin`` checks in :mod:`._auth` — and never
+hard-fails a request. There is deliberately NO ``Cross-Origin-Embedder-Policy: require-corp``: COEP
+gates EVERY subresource on an explicit CORP/CORS opt-in and would break the same-origin ``/ui/static``
+assets and the ``data:`` images the /ui CSP already allows, for no isolation gain on a surface that
+embeds no cross-origin content.
+
+**Which relied-on features are actively DETECTED, and which degrade silently (ASVS 3.7.5).** The
+contract above is only testable if it says, per feature, what the console does when the feature is
+absent. Three sets are enumerated below, each entry in exactly one bucket — detected-and-warned, or
+degrades-silently-with-a-named compensating control:
+
+1. every **browser-security response header** that reaches a ``/ui`` response — including the ones
+   emitted by the ENGINE's own security-headers middleware (``api/app.py``) rather than by this one;
+2. every **client-side browser security feature the console feature-detects** in its own scripts
+   (``static/app.js`` and the nonce'd shell scripts in :mod:`._html`);
+3. the **session cookie's security attributes** (``__Host-`` prefix / ``Secure`` / ``HttpOnly`` /
+   ``SameSite``), which no page script can observe at all.
+
+This list is the in-code source of truth the runbook's operator-facing copy mirrors, and a CI guard
+(``test_ui_csp_canary.py``) derives all three sets from the CODE — the header writes, the
+``window.<Feature>`` reads, and the ``set_cookie`` attributes — and fails if any member is missing
+here or from the runbook, so a newly-shipped header, detect or cookie attribute cannot slip in
+unbucketed. Anything OUTSIDE those three sets is outside the claim.
+
+* **Secure transport context** — DETECTED and WARNED. The nonce'd page-shell script reads
+  ``window.isSecureContext``; false raises a visible ``role="alert"`` banner
+  (:mod:`._html`). Correctly inert on the loopback posture, where ``http://127.0.0.1`` IS a secure
+  context; it exists for the proxy-TLS mismatch the engine cannot see server-side.
+* **CSP enforcement** (``Content-Security-Policy`` honoured at all) — DETECTED and WARNED. The shell
+  loads an UN-NONCED external canary (``/ui/static/csp-probe.js``); an enforcing browser refuses it
+  under ``script-src 'nonce-…' 'strict-dynamic'`` so its global stays undefined, while a browser that
+  does not enforce CSP runs it and the nonce'd detect raises a second ``role="alert"`` banner. This is
+  an ACTIVE detect that fires on the default deployment: the flag can only be set when the policy is
+  not being applied. Its expected violation reports are filtered out of the log by SAME-ORIGIN
+  blocked-URL path, per report entry — never per batch — so a real violation delivered in the same
+  Reporting-API POST still warns (:mod:`.routes.core`).
+* **CSP nonce-source support / script execution** — DETECTED and WARNED, by the INVERSE detect. A
+  browser that ENFORCES CSP but does not understand ``'nonce-…'``/``'strict-dynamic'`` has no valid
+  script source and blocks EVERY script — app.js, both detects above, and the ASVS 14.3.1 session
+  watchdog — so no script-raised banner could render (the same is true with JavaScript disabled). The
+  shell therefore SERVER-renders a ``role="alert"`` banner (id ``mf-scripts-blocked-banner``) that a
+  nonce'd mark script removes from view (via an ``<html>`` class app.css keys on) on a healthy
+  client: fail-visible, no flash, and it stands exactly when scripts do not run. **Named residual:**
+  the ASVS 14.3.1 session watchdog is one of the blocked scripts, so a timed-out tab keeps its
+  rendered PHI page until the operator navigates. Compensating: everything the blocked scripts carry
+  is client-side BELT — the server still refuses every subsequent request (idle + absolute expiry,
+  RBAC and auditing are untouched), the expiry redirect still carries ``Clear-Site-Data``, and every
+  /ui HTML response is ``Cache-Control: no-store``.
+* **``window.PublicKeyCredential`` (WebAuthn passkeys)** — DETECTED and WARNED. ``static/app.js``
+  reads it before wiring either passkey ceremony; when it is absent the button is DISABLED and the
+  status line says so in place ("This browser does not support passkeys." on enrolment, "…— use your
+  password/code." on the step-up leg), so the operator is told rather than left clicking a control
+  that silently does nothing. Compensating: a passkey is an ALTERNATIVE factor, never the only one —
+  the TOTP and password legs are untouched, so a browser without WebAuthn can still enroll MFA,
+  complete a step-up and sign in. (The RP-configuration failures — the ``[webauthn]`` extra absent, or
+  no resolvable RP id — are a SERVER-side fail-closed notice, not a browser-support case.)
+* **Session-cookie security attributes — ``__Host-`` prefix / ``Secure`` / ``HttpOnly``** — DEGRADE
+  SILENTLY, necessarily: ``HttpOnly`` is precisely what stops a page script from reading the cookie,
+  so none of the three is observable client-side (``SameSite`` has its own row below for the same
+  reason). Compensating: they are only ever SET where a browser will honour them — the ``__Host-``
+  prefix and ``Secure`` key on :func:`._auth.effective_https`, so cleartext loopback keeps the plain
+  ``mf_session`` rather than a cookie the browser would silently reject and thereby break login —
+  session termination is SERVER-side (revoke + ``Clear-Site-Data``, never cookie deletion alone), and
+  every state-changing /ui POST carries the server-side ``Sec-Fetch-Site``/``Origin`` check, so a
+  browser that ignores the attributes still cannot be driven cross-site with the cookie.
+* **``Cross-Origin-Opener-Policy``** — DEGRADES SILENTLY, by necessity. No browser API exposes COOP
+  enforcement to the page. ``window.crossOriginIsolated`` is NOT a COOP detect — it additionally
+  requires COEP, which is deliberately not set (above), so reading it would render a false "degraded"
+  banner in every browser. The compensating posture is that COOP is pure defense-in-depth here: /ui
+  opens no cross-origin windows and embeds no cross-origin content, so its absence costs process
+  isolation only, and ``frame-ancestors 'none'`` still blocks framing.
+* **``Cross-Origin-Resource-Policy``** — DEGRADES SILENTLY, same rationale: no client-observable API,
+  and /ui serves no resource intended for cross-origin embedding.
+* **``Reporting-Endpoints``** — DEGRADES SILENTLY. It only routes violation reports, so a client that
+  ignores it costs telemetry, never a control; the legacy ``report-uri`` directive is emitted
+  alongside it, so most such clients still deliver reports.
+* **``SameSite=Strict`` on the session cookie** — DEGRADES SILENTLY, with a compensating control that
+  makes the degradation non-fatal rather than merely unwarned: a page script cannot read an HttpOnly
+  cookie's SameSite attribute, so the absence is undetectable client-side, but every state-changing
+  ``/ui`` POST — including the unauthenticated ``/ui/login`` and the gate-less ``/ui/logout`` — carries
+  an explicit server-side ``Sec-Fetch-Site``/``Origin`` check (:func:`._auth.assert_same_origin`,
+  ASVS 3.5.1). A browser that ignores SameSite therefore still cannot mount CSRF against /ui.
+* **``Clear-Site-Data``** (ASVS 14.3.1; emitted by :mod:`._auth` on every login redirect and by
+  :mod:`.routes.core` on logout and the post-termination login render) — DEGRADES SILENTLY; Safari
+  has no support. Compensating: it is only the Back/bfcache belt. The session is revoked SERVER-side,
+  the cookie is explicitly deleted, every /ui HTML response carries ``Cache-Control: no-store``, and
+  the 14.3.1 watchdog blanks the rendered document synchronously before navigating away.
+* **``Cache-Control: no-store``** on /ui HTML and PHI JSON (engine middleware) — DEGRADES SILENTLY: a
+  page script cannot observe another response's cache treatment. Compensating: ``Clear-Site-Data`` on
+  session termination, the watchdog's document blanking, and the server refusing every request the
+  resurrected page would make.
+* **``X-Content-Type-Options: nosniff``** (engine middleware) — DEGRADES SILENTLY. Compensating: the
+  /ui static mount serves ONLY ``.css``/``.js`` from a fixed directory with correct MIME types (ASVS
+  13.4.7, :mod:`._static`), and no user-supplied file is ever served from the /ui origin.
+* **``X-Frame-Options: DENY``** (engine middleware) — DEGRADES SILENTLY, and is pure legacy
+  redundancy: the CSP's ``frame-ancestors 'none'`` is the modern control and every browser that
+  honours the nonce CSP honours it.
+* **``Referrer-Policy: no-referrer``** (engine middleware) — DEGRADES SILENTLY. Compensating: the same
+  policy is ALSO carried in-document by ``<meta name="referrer" content="no-referrer">`` in every page
+  shell (:func:`._html.page`), /ui URLs carry opaque ids only (never PHI), and ``/ui`` links off-site
+  nowhere.
+* **``Strict-Transport-Security``** (engine middleware, effective-https only) — DEGRADES SILENTLY.
+  Compensating: TLS is terminated by the documented reverse proxy, which is configured to redirect
+  cleartext, and the ``window.isSecureContext`` banner above makes a cleartext hop visible to the
+  operator.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ._auth import browser_hardening_enabled, security_headers_context
+from ._html import reset_csp_nonce, set_csp_nonce
+
+#: The route (registered in :mod:`.routes.core`) the browser POSTs CSP violation reports to, and the
+#: ``Reporting-Endpoints`` group name that references it.
+CSP_REPORT_PATH = "/ui/csp-report"
+CSP_REPORT_GROUP = "mf-csp"
+
+#: Cross-origin isolation headers set on every effective-https /ui HTML response.
+COOP_VALUE = "same-origin"
+CORP_VALUE = "same-origin"
+
+#: Every browser-security response header :class:`UiSecurityHeadersMiddleware` writes. Declared here
+#: so the ASVS 3.7.5 degrade-contract guard can read the emitted set from CODE instead of a literal in
+#: the test; the guard also re-derives it from the ``send_wrapper`` source, so this tuple cannot drift
+#: away from what is actually emitted (see ``test_ui_csp_canary.py``).
+#:
+#: Deliberately a DECLARATION with no runtime consumer — the middleware writes the headers directly so
+#: the emitting code stays readable in one place. Its consumer is the contract guard, and its job is
+#: to be the thing that guard compares the source against; do not "clean it up" into the send_wrapper.
+SECURITY_HEADER_NAMES: tuple[str, ...] = (
+    "Content-Security-Policy",
+    "Cross-Origin-Opener-Policy",
+    "Cross-Origin-Resource-Policy",
+    "Reporting-Endpoints",
+)
+
+_NONCE_BYTES = 16  # secrets.token_urlsafe(16) -> 22 url-safe chars, ample CSP nonce entropy
+
+
+def build_ui_csp(nonce: str) -> str:
+    """The /ui CSP for an effective-https response: the static self-only base with ``script-src``
+    upgraded to a per-response nonce + ``strict-dynamic`` (3.4.7/3.4.8) and CSP reporting wired to
+    :data:`CSP_REPORT_PATH`. ``strict-dynamic`` intentionally drops the host allowlist for scripts —
+    only the nonce'd first-party ``app.js`` (and anything it loads) runs; there is no inline script."""
+    return (
+        f"default-src 'self'; script-src 'nonce-{nonce}' 'strict-dynamic'; style-src 'self'; "
+        "img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'; "
+        "base-uri 'none'; form-action 'self'; object-src 'none'; "
+        f"report-uri {CSP_REPORT_PATH}; report-to {CSP_REPORT_GROUP}"
+    )
+
+
+def _is_ui_html_path(path: str) -> bool:
+    """The engine's exact /ui-HTML scope: a /ui path that is not a /ui/static asset."""
+    return (path == "/ui" or path.startswith("/ui/")) and not path.startswith("/ui/static")
+
+
+class UiSecurityHeadersMiddleware:
+    """Pure-ASGI /ui browser-security hardening (see the module docstring)."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or not _is_ui_html_path(scope.get("path", "")):
+            await self.app(scope, receive, send)
+            return
+        app_state = getattr(scope.get("app"), "state", None)
+        if not browser_hardening_enabled() or not security_headers_context(
+            app_state, scope.get("scheme", "http")
+        ):
+            # Opt-out, or a cleartext NON-loopback context with no exposure_protected: strict no-op ->
+            # the engine's static /ui CSP response stands byte-for-byte (the org opt-out reverts every
+            # scheme; a loopback secure-context now ENGAGES the http-safe headers via
+            # security_headers_context, ADR 0143 — see the module docstring).
+            await self.app(scope, receive, send)
+            return
+        nonce = secrets.token_urlsafe(_NONCE_BYTES)
+        csp = build_ui_csp(nonce)
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                headers = MutableHeaders(scope=message)
+                headers["Content-Security-Policy"] = csp
+                headers["Cross-Origin-Opener-Policy"] = COOP_VALUE
+                headers["Cross-Origin-Resource-Policy"] = CORP_VALUE
+                headers["Reporting-Endpoints"] = f'{CSP_REPORT_GROUP}="{CSP_REPORT_PATH}"'
+            await send(message)
+
+        token = set_csp_nonce(nonce)
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            reset_csp_nonce(token)

messagefoundry_webconsole/_service.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""The console's own :class:`AuthService` provider dependency.
+
+A trivial re-implementation of ``api.auth_routes._service`` (get + enabled-check reading
+``app.state``) so the package never imports ``auth_routes`` — which would form a
+package → auth_routes → package cycle. Identical semantics: absent/disabled auth → 503.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, Request, status
+
+from messagefoundry.api.security import get_auth
+from messagefoundry.auth.service import AuthService
+
+
+def _service(request: Request) -> AuthService:
+    auth = get_auth(request)
+    if auth is None or not auth.enabled:
+        raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "authentication is not enabled")
+    return auth

messagefoundry_webconsole/_static.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Extension-allowlisting static file serving for ``/ui/static`` (ASVS 13.4.7).
+
+Starlette's :class:`~starlette.staticfiles.StaticFiles` serves **any regular file** under its
+directory. Its only containment is path-traversal defence (a ``commonpath`` check plus symlink
+refusal) — there is no extension policy, no dotfile rule and no backup-suffix rule anywhere in it.
+Verified empirically against the shipped Starlette: a bare mount happily serves ``.env``,
+``app.js.bak``, ``secrets.map``, ``x.py``, extension-less files and files in subdirectories.
+
+That matters here because the console's asset directory IS the served surface: the wheel
+force-includes the whole package tree with no exclude list, and dev/CI install it editable, so
+``STATIC_DIR`` resolves to the live working tree with no build step standing between a stray file and
+an UNAUTHENTICATED 200 (the ``/ui/static`` prefix is excluded from the /ui auth and no-store paths).
+The worst instance is invisible to review: a ``.env`` dropped in there is matched by the repo
+``.gitignore``, so ``git status``, diffs and PR review all skip it while it is served.
+
+:class:`AllowlistedStaticFiles` closes that by construction rather than by curation: a request is
+resolved only when its path's final component has exactly ONE suffix and that suffix is in
+:data:`ALLOWED_STATIC_EXTENSIONS`. Everything else 404s *before* the filesystem is touched. It is the
+second of three layers — the packaging manifest test (asset directory contents) and the planted-file
+runtime test are the others; the runtime allowlist alone would still serve an ALLOWED-extension
+accident such as a stray second ``.js``.
+
+**Any future static mount must reuse this class**, not ``StaticFiles``: the allowlist governs the
+mount it is installed on, not the process.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import PurePosixPath
+
+from starlette.staticfiles import StaticFiles
+
+__all__ = ["ALLOWED_STATIC_EXTENSIONS", "AllowlistedStaticFiles", "static_path_allowed"]
+
+#: The ONLY file extensions ``/ui/static`` will serve — exactly the kinds of asset the console ships
+#: (stylesheet, script). Lowercase, leading dot. Adding one is a reviewed security decision: it widens
+#: an unauthenticated, uncached, same-origin file-serving surface.
+ALLOWED_STATIC_EXTENSIONS = frozenset({".css", ".js"})
+
+
+def static_path_allowed(path: str) -> bool:
+    """Whether ``path`` (relative, as Starlette hands it to ``lookup_path``) may be served.
+
+    Allowed only when the final component has exactly one suffix and that suffix is allow-listed.
+    That single rule rejects each named class at once:
+
+    * **dotfiles** — ``.env`` / ``.htpasswd``: no stem, so ``PurePosixPath.suffixes`` is empty;
+    * **multi-suffix backup/derived forms** — ``app.js.bak``, ``app.css.map``: two suffixes, refused
+      even when the LAST one is allow-listed (``notes.bak.js`` too), because a backup of a served
+      asset is a different artifact from the asset;
+    * **extension-less files** — ``notes``, ``Dockerfile``: no suffix;
+    * **anything else** — ``x.py``, ``connections.toml``, ``deep.key``, in this directory or any
+      subdirectory of it, since the rule is applied to the final component of the WHOLE relative path.
+    """
+    normalized = PurePosixPath(path.replace(os.sep, "/"))
+    name = normalized.name
+    if not name or name in (".", ".."):
+        return False
+    suffixes = PurePosixPath(name).suffixes
+    return len(suffixes) == 1 and suffixes[0].lower() in ALLOWED_STATIC_EXTENSIONS
+
+
+class AllowlistedStaticFiles(StaticFiles):
+    """:class:`StaticFiles` restricted to :data:`ALLOWED_STATIC_EXTENSIONS`.
+
+    The filter lands in ``lookup_path`` — the one funnel every resolution goes through — so a
+    disallowed name is refused BEFORE any ``os.stat``, and returning the miss sentinel makes the base
+    class raise its own ``404`` (``html=False``, so there is no index/404 fallback that could resolve
+    a second path behind our back).
+    """
+
+    def lookup_path(self, path: str) -> tuple[str, os.stat_result | None]:
+        if not static_path_allowed(path):
+            return "", None
+        return super().lookup_path(path)

messagefoundry_webconsole/mount.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""``mount_ui(app, deps)`` — the single entrypoint ``create_app`` calls to graft the web console onto
+the engine's FastAPI app, same-origin (Option B, ADR 0065).
+
+It (1) re-asserts the engine seam (belt-and-suspenders — the engine already asserted before building
+``deps``), (2) installs the three always-on app.state hooks the JSON engine reads when serve_ui is on
+(the /ui CSP, the browser-cookie WS authorizer, the server-rendered connections fragment), (3) mounts
+the package's own static assets, and (4) registers every /ui route in a fixed, test-pinned order.
+
+The route modules are imported at THIS module's import time (eager), so every module-level
+``register_ui_action`` has fired before serving — the write-action registry is a single authoritative
+module-global (``_auth._UI_WRITE_ACTIONS``). NOTE (review fix): there is deliberately NO mount-time
+"every step-up route has a registry entry" self-check — that is a FALSE invariant (body-carrying
+step-up POSTs map their stale-window redirect via ``reauth_next`` to a DIFFERENT registered unlock
+page, so they intentionally have no own entry). Registry/route completeness is backstopped by the
+moved tests + a golden route-table test instead.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from messagefoundry.api._ui_seam import UiDeps
+
+from . import STATIC_DIR, _auth, assert_engine_seam, pages
+from ._security import UiSecurityHeadersMiddleware
+from ._static import AllowlistedStaticFiles
+from .routes import (
+    account,
+    admin,
+    audit,
+    config,
+    connection_writes,
+    core,
+    monitoring,
+    monitoring_writes,
+    oidc,
+    search,
+    sso,
+    status,
+    uploaded_logs,
+)
+
+# Fixed registration order, pinned by the golden route-table test. This reproduces the pre-extraction
+# order: add_auth_routes registered its admin/account/audit /ui routes first, then create_app's
+# _UI_REGISTRARS (search FIRST so the literal /ui/messages/search beats /ui/messages/{id}; the literal
+# bulk/purge-confirm paths are registered before {name}/purge/{scope} WITHIN connection_writes).
+_REGISTRARS = (
+    admin,
+    account,
+    audit,
+    search,
+    core,
+    uploaded_logs,
+    monitoring,
+    status,
+    monitoring_writes,
+    connection_writes,
+    config,
+    sso,
+    # Self-gating: registers nothing unless [auth].oidc_enabled, so the golden route table
+    # is unchanged for the default-off build (ADR 0142 AC-1). Tail placement is safe --
+    # both paths are literal, with no {param} sibling anywhere in the table to shadow.
+    oidc,
+)
+
+
+def mount_ui(app: FastAPI, deps: UiDeps) -> None:
+    """Mount the entire /ui web console onto ``app``, wiring the moved routes to the injected
+    ``deps`` bundle.
+
+    Route registration is append-by-pattern and the security middleware is explicitly guarded, so a
+    re-mount of the SAME app does not stack a second, nonce-conflicting copy of it. The static mount
+    is NOT guarded — ``create_app`` builds a fresh ``FastAPI`` per call, so it is never re-mounted in
+    practice; a re-mount would simply shadow with an identical entry."""
+    assert_engine_seam(deps.engine_seam)
+    # Always-on seams the JSON engine reads when serve_ui is on (Option B Phase 0): the /ui CSP
+    # (co-versioned with app.js/app.css), the browser-cookie WS authorizer (CSWSH-guarded), and the
+    # server-rendered connections fragment pushed over /ws/stats. With the console absent these stay
+    # unset, so the security-headers middleware and /ws/stats take their JSON-only fallbacks.
+    app.state.ui_csp = _auth.UI_CSP
+    app.state.ui_ws_authorize = _auth.authorize_ui_ws
+    app.state.ui_connections_render = pages.connections_fragment
+
+    # ASVS 13.4.7: the console's asset tier serves ONLY allow-listed extensions. A bare StaticFiles
+    # serves any regular file under the directory, and this directory IS the working tree under the
+    # editable dev/CI install — so a stray .map/backup/.env is otherwise an unauthenticated 200. Any
+    # future static mount must use AllowlistedStaticFiles too; the allowlist governs the mount, not
+    # the process. See :mod:`._static`.
+    app.mount("/ui/static", AllowlistedStaticFiles(directory=str(STATIC_DIR)), name="ui-static")
+
+    for module in _REGISTRARS:
+        module.register(app, deps)
+
+    # Install the /ui browser-security hardening LAST so Starlette makes it the OUTERMOST middleware
+    # (added after the engine's security-headers middleware): its response send-wrapper runs last and
+    # thus owns the effective-https /ui CSP/COOP/reporting headers, while deferring to the engine's
+    # static app.state.ui_csp untouched over cleartext loopback (byte-identity). Guarded so a re-mount
+    # of the SAME app (the idempotency contract above) does not stack a second, nonce-conflicting copy.
+    # See :mod:`._security`.
+    if not any(getattr(m, "cls", None) is UiSecurityHeadersMiddleware for m in app.user_middleware):
+        app.add_middleware(UiSecurityHeadersMiddleware)

messagefoundry_webconsole/pages/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""HTML page/fragment builders for the /ui ops dashboard (ADR 0065), split by console area.
+
+Every builder returns :class:`.._html.Markup`; every dynamic value is placed through the escaping
+element builders in :mod:`.._html`, so attacker-influenced HL7/message content cannot inject markup.
+No page emits inline script or ``on*`` handlers (CSP ``script-src 'self'``).
+
+**Per-area package (ADR 0065 §multi-session-build).** Builders live in per-area modules so file
+ownership matches lane ownership — a lane adds a page as a ``def`` + its name in that module's own
+``__all__`` (a lane-private edit), with **no** shared central list to collide on. Callers keep using
+``webui.pages.<fn>``; this ``__init__`` re-exports each module's public builders and is edited **only**
+when a lane adds a wholly new area module.
+"""
+
+from __future__ import annotations
+
+from .account import *  # noqa: F401,F403
+from .admin import *  # noqa: F401,F403
+from .audit import *  # noqa: F401,F403
+from .config import *  # noqa: F401,F403
+from .connections import *  # noqa: F401,F403
+from .messages import *  # noqa: F401,F403
+from .monitoring import *  # noqa: F401,F403
+from .uploaded_logs import *  # noqa: F401,F403

messagefoundry_webconsole/pages/_common.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Shared cell/format helpers for the /ui page builders (ADR 0065).
+
+Small, escape-neutral formatters imported by the per-area page modules (``connections``,
+``messages``, …) so the rendering conventions live in one place, never copy-pasted per module.
+"""
+
+from __future__ import annotations
+
+
+def _num(value: object) -> str:
+    """Render a count/None as text ('—' for None)."""
+    return "—" if value is None else str(value)
+
+
+def _secs(value: float | None) -> str:
+    """Render an age in seconds as a compact string ('—' for None)."""
+    if value is None:
+        return "—"
+    return f"{value:.0f}s"