flask-construct-ui 0.9.5__py3-none-any.whl

flask_construct_ui/__init__.py

@@ -0,0 +1,82 @@
+from .base import FlaskConstructUI as FlaskConstructUI
+from .base import PageBase as PageBase
+from .crud import CrudPageBase as CrudPageBase, RelatedCrudTab as RelatedCrudTab
+from .base import BaseIndexView as BaseIndexView
+from .base import expose as expose
+from .base import list_action as list_action
+from .base import tab_action as tab_action
+from .base import edit_action as edit_action
+from .base import datasource as datasource
+from .base import livesource as livesource
+from .base import SSE_DONE as SSE_DONE
+
+# Component-based pages and the component library. Exposed at the package root
+# so ComponentPageBase apps and companion/extension authors can build UI from
+# component trees without reaching into submodules. The `components` namespace
+# (e.g. ``components.Card(...)``) is the idiomatic accessor; the individual
+# classes are exported too for explicit imports and type hints.
+from .base import ComponentPageBase as ComponentPageBase
+from .components import (
+    components as components,
+    Component as Component,
+    Field as Field,
+    ChartType as ChartType,
+    find_component as find_component,
+    find_component_by_id as find_component_by_id,
+    LiveComponent as LiveComponent,
+    VerticalLayoutComponent as VerticalLayoutComponent,
+    HorizontalLayoutComponent as HorizontalLayoutComponent,
+    GridLayoutComponent as GridLayoutComponent,
+    CardComponent as CardComponent,
+    TabsComponent as TabsComponent,
+    FormComponent as FormComponent,
+    ChartComponent as ChartComponent,
+    TextComponent as TextComponent,
+    MarkupComponent as MarkupComponent,
+    RichTextComponent as RichTextComponent,
+    ButtonComponent as ButtonComponent,
+    TableComponent as TableComponent,
+    CalendarComponent as CalendarComponent,
+)
+
+# Authentication & authorization
+from .auth import (
+    AuthProvider as AuthProvider,
+    FlaskSecurityAuth as FlaskSecurityAuth,
+    FlaskOIDCAuth as FlaskOIDCAuth,
+    public as public,
+    require_groups as require_groups,
+)
+
+# Navbar features
+from .navbar import (
+    NavbarFeature as NavbarFeature,
+    GlobalSearch as GlobalSearch,
+    Notifications as Notifications,
+    Notice as Notice,
+    SearchResult as SearchResult,
+)
+
+# from .data_sqlalchemy import DataSQLAlchemy
+from .schema import dataschema as dataschema
+from .schema import schema as schema
+from .schema import SchemaField as SchemaField
+
+# Icon registry (for extension/companion libraries)
+from .icons import (
+    register_icons as register_icons,
+    render_icon as render_icon,
+    ICONS as ICONS,
+)
+
+# Headless sub-library helpers
+from .headless import (
+    sse_event as sse_event,
+    sse_response as sse_response,
+    live_attributes as live_attributes,
+    live_container as live_container,
+)
+
+# HTML sanitizer (allowlist-based; for trusted-HTML surfaces such as
+# LiveComponent format="raw" and TextComponent format="html")
+from .sanitize import sanitize_html as sanitize_html

flask_construct_ui/auth.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from flask import (
+    abort,
+    current_app,
+    g,
+    redirect,
+    render_template,
+    request,
+    url_for,
+)
+
+# --- Authentication & authorization ---------------------------------------
+# Construct routes are guarded fail-closed: once an ``AuthProvider`` is passed
+# to ``FlaskConstructUI(auth=...)`` every construct-owned route requires login
+# by default. Routes opt out with ``@public`` (or a page-wide
+# ``login_required = False``) and opt up with ``@require_groups(...)`` (or a
+# page-wide ``required_groups``). The enforcement point is a blueprint-scoped
+# ``before_request`` in ``base.py`` (see ``auth_protect``), which is why this
+# covers the dynamically-registered RCRUD nested routes too.
+#
+# The boundary is server-side, so it behaves identically with JavaScript on or
+# off: an unauthenticated request gets a plain 302 to the login endpoint (a
+# browser follows it without JS; Unpoly follows it too) and an authenticated
+# request lacking the required group gets a server-rendered themed 403 page.
+
+
+def public(f):
+    """Mark a view as not login-protected (reachable while unauthenticated)."""
+    f._construct_auth = {"public": True}
+    return f
+
+
+def require_groups(*groups, mode="any"):
+    """Require the current user to belong to the given group(s).
+
+    ``mode="any"`` (default) passes if the user is in at least one of
+    ``groups``; ``mode="all"`` requires membership in every one. Implies login.
+    """
+
+    def wrap(f):
+        f._construct_auth = {"groups": tuple(groups), "mode": mode}
+        return f
+
+    return wrap
+
+
+class AuthProvider:
+    """Adapter between Construct's route guard and a host auth stack.
+
+    Subclasses only need to answer two questions — ``is_authenticated`` and
+    ``current_groups``. The response helpers below are concrete and Unpoly-aware
+    and are rarely overridden. Ship-with adapters: :class:`FlaskSecurityAuth`,
+    :class:`FlaskOIDCAuth`. Write a custom one by subclassing this.
+    """
+
+    #: Flask endpoint name (or literal path) to send unauthenticated users to.
+    #: Overridden by the ``CONSTRUCT_LOGIN_ENDPOINT`` config when set.
+    login_endpoint = None
+
+    def is_authenticated(self) -> bool:
+        raise NotImplementedError
+
+    def current_groups(self) -> set[str]:
+        """Return the set of group/role names the current user belongs to."""
+        return set()
+
+    def has_groups(self, required, mode="any") -> bool:
+        have = self.current_groups()
+        if mode == "all":
+            return all(g in have for g in required)
+        return any(g in have for g in required)
+
+    def current_user_name(self) -> str | None:
+        """Display name for the logged-in user, or None if unavailable."""
+        return None
+
+    def current_user(self) -> dict | None:
+        """Normalized view of the logged-in user, or None if unauthenticated.
+
+        Returns a dict with at least ``name`` (display name) and ``groups``
+        (a ``set`` of group/role names) keys. Adapters override this to fold in
+        provider-specific claims (e.g. ``email``, ``sub``). Application code
+        should prefer this -- or the conveniences built on it,
+        ``PageBase.current_user`` and the ``current_user`` template global --
+        over reaching into a provider's native session, so it stays portable
+        across auth stacks.
+        """
+        if not self.is_authenticated():
+            return None
+        return {
+            "name": self.current_user_name(),
+            "groups": self.current_groups(),
+        }
+
+    def user_menu_items(self) -> list[dict]:
+        """Items for the user dropdown menu.
+
+        Each dict must have ``label`` and ``url`` keys; ``icon`` is optional
+        and may be a semantic icon name (see ``icons.ICONS``) or a raw glyph;
+        it is rendered in the active icon mode (Material Symbols by default,
+        Bootstrap Icons under the ``adminlte`` design).
+        """
+        return []
+
+    # -- response helpers ---------------------------------------------------
+
+    def login_url(self):
+        """Resolve the login URL, carrying ``next`` back to this request."""
+        target = (
+            current_app.config.get("CONSTRUCT_LOGIN_ENDPOINT") or self.login_endpoint
+        )
+        nxt = request.full_path.rstrip("?")
+        if not target:
+            # No login endpoint configured: fall back to a bare 401.
+            return None
+        try:
+            return url_for(target, next=nxt)
+        except Exception:
+            # Not a known endpoint — treat it as a literal path.
+            sep = "&" if "?" in target else "?"
+            return f"{target}{sep}next={nxt}"
+
+    def on_unauthenticated(self):
+        """Default: 302 redirect to the login URL (401 if none configured)."""
+        url = self.login_url()
+        if url is None:
+            abort(401)
+        return redirect(url)
+
+    def on_forbidden(self):
+        """Default: render the themed access-denied page with HTTP 403."""
+        construct = getattr(g, "construct", None)
+        theme = getattr(construct, "theme", None) or "whitelabel"
+        return render_template(
+            f"themes/{theme}/errors/forbidden.html", construct=construct
+        ), 403
+
+
+class FlaskSecurityAuth(AuthProvider):
+    """Adapter for Flask-Security(-Too): ``current_user`` + role relationship."""
+
+    login_endpoint = "security.login"
+
+    def is_authenticated(self) -> bool:
+        from flask_security import current_user  # lazy: optional dependency
+
+        return bool(current_user.is_authenticated)
+
+    def current_groups(self) -> set[str]:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return set()
+        return {role.name for role in current_user.roles}
+
+    def current_user_name(self) -> str | None:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return None
+        return getattr(current_user, "username", None) or getattr(
+            current_user, "email", None
+        )
+
+    def current_user(self) -> dict | None:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return None
+        return {
+            "name": self.current_user_name(),
+            "groups": self.current_groups(),
+            "id": getattr(current_user, "id", None),
+            "username": getattr(current_user, "username", None),
+            "email": getattr(current_user, "email", None),
+        }
+
+    def user_menu_items(self) -> list[dict]:
+        try:
+            from flask import url_for
+
+            return [
+                {
+                    "label": "Sign out",
+                    "url": url_for("security.logout"),
+                    "icon": "logout",
+                }
+            ]
+        except Exception:
+            return []
+
+
+class FlaskOIDCAuth(AuthProvider):
+    """Adapter for Flask-OIDC: login state + group/role claims from the token.
+
+    ``oidc`` is the application's ``OpenIDConnect`` instance. ``groups_claim`` is
+    the claim carrying the user's groups/roles — on Flask-OIDC 2.x this is read
+    from the userinfo response (so the IdP must include it there, with
+    ``OIDC_USER_INFO_ENABLED`` on), on older builds from the decoded id-token.
+    Flask-OIDC's claim API differs across major versions, so claim access is
+    isolated in :meth:`current_groups` to make it easy to adapt. The default
+    ``login_endpoint`` matches Flask-OIDC 2.x, which registers its routes under
+    the ``oidc_auth`` blueprint.
+    """
+
+    def __init__(
+        self,
+        oidc,
+        groups_claim="groups",
+        login_endpoint="oidc_auth.login",
+        logout_endpoint="oidc_auth.logout",
+    ):
+        self.oidc = oidc
+        self.groups_claim = groups_claim
+        self.login_endpoint = login_endpoint
+        self.logout_endpoint = logout_endpoint
+
+    def is_authenticated(self) -> bool:
+        return bool(getattr(self.oidc, "user_loggedin", False))
+
+    def _claims(self) -> dict:
+        """Best-effort full claim set for the current user.
+
+        Flask-OIDC 2.x stores the userinfo response in the session under
+        ``oidc_auth_profile``; older builds keep the decoded id-token on
+        ``flask.g``. Returns ``{}`` when neither is present (or when called
+        outside a request context).
+        """
+        try:
+            from flask import session
+
+            profile = session.get("oidc_auth_profile")
+            if isinstance(profile, dict):
+                return profile
+            token = g.get("oidc_id_token", None)
+            if isinstance(token, dict):
+                return token
+        except RuntimeError:
+            pass
+        return {}
+
+    def current_groups(self) -> set[str]:
+        if not self.is_authenticated():
+            return set()
+        # Newer Flask-OIDC exposes claims via user_getfield; older builds keep
+        # the decoded id-token on flask.g. Prefer the accessor when present.
+        getter = getattr(self.oidc, "user_getfield", None)
+        if getter is not None:
+            return set(getter(self.groups_claim) or [])
+        token = g.get("oidc_id_token", None)
+        if isinstance(token, dict):
+            return set(token.get(self.groups_claim) or [])
+        return set()
+
+    def current_user_name(self) -> str | None:
+        if not self.is_authenticated():
+            return None
+        getter = getattr(self.oidc, "user_getfield", None)
+        if getter is not None:
+            return getter("name") or getter("email")
+        token = g.get("oidc_id_token", None)
+        if isinstance(token, dict):
+            return token.get("name") or token.get("email")
+        return None
+
+    def current_user(self) -> dict | None:
+        if not self.is_authenticated():
+            return None
+        # Start from the full claim set so callers get email/sub/custom claims
+        # without reaching into Flask-OIDC's session, then overlay the
+        # normalized name/groups so the shape matches other adapters.
+        user = dict(self._claims())
+        user["name"] = self.current_user_name()
+        user["groups"] = self.current_groups()
+        return user
+
+    def user_menu_items(self) -> list[dict]:
+        try:
+            from flask import url_for
+
+            return [
+                {
+                    "label": "Sign out",
+                    "url": url_for(self.logout_endpoint),
+                    "icon": "logout",
+                }
+            ]
+        except Exception:
+            return []