simple-module-core 0.0.32__tar.gz → 0.0.33__tar.gz

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.32
+Version: 0.0.33
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.32"
+version = "0.0.33"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/__init__.py

@@ -1,6 +1,6 @@
 """SimpleModule Core - Module system, menu, permissions, events, and diagnostics."""
 
-from simple_module_core.audit_links import AuditLink, AuditLinkRegistry
+from simple_module_core.audit_links import AuditLink, AuditLinkRegistry, LabelResolver
 from simple_module_core.csp import CspSourceError, CspSourceRegistry
 from simple_module_core.design_packs import DesignPack, DesignPackRegistry
 from simple_module_core.diagnostics import (
@@ -41,6 +41,7 @@ from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
 from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
 from simple_module_core.services import Services
+from simple_module_core.setup_steps import SetupRegistry, SetupStep
 from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
 
 __all__ = [
@@ -65,6 +66,7 @@ __all__ = [
     "HealthStatus",
     "I18nRegistry",
     "InvalidModuleError",
+    "LabelResolver",
     "MenuItem",
     "MenuRegistry",
     "MenuSection",
@@ -77,6 +79,8 @@ __all__ = [
     "PublicRoute",
     "PublicRouteRegistry",
     "Services",
+    "SetupRegistry",
+    "SetupStep",
     "Translator",
     "ValidationError",
     "check_framework_compatibility",

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/audit_links.py

@@ -19,7 +19,23 @@ the target route as usual.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+LabelResolver = Callable[[Any, list[str]], Awaitable[dict[str, str]]]
+"""Batch "what is this row called" for one entity type.
+
+Called with the request's database session and every entity id of that type on
+the page, and returns ``{entity_id: display name}``. Ids it cannot name are
+simply absent — the caller falls back to the id, which is what the audit row
+actually stored.
+
+The session is typed ``Any`` because ``simple_module_core`` must not depend on
+SQLAlchemy; in practice it is the ``AsyncSession`` the request is already
+using, so a resolver adds one query per entity type per page and no session
+management of its own.
+"""
 
 _ID_PLACEHOLDER = "{id}"
 
@@ -36,24 +52,51 @@ class AuditLink:
             unmatched lookup falls back to showing ``entity_type`` as the
             label, a table-name key looks like it worked.
         url_template: Path containing ``{id}``, substituted with the entity id
-            (e.g. ``"/admin/users/{id}/edit"``).
+            (e.g. ``"/admin/users/{id}/edit"``). Empty means *these rows have
+            no screen* — join tables and stored files are audited but have
+            nowhere to open — and the cell renders the name unlinked. A module
+            still registers those, because it is the only thing that knows what
+            the table is called and what its rows are named.
         label: Human-readable name for the entity kind, shown instead of the
             raw class name (e.g. ``"User account"``).
+        label_key: Catalog key for ``label``. Empty, or unresolved, falls back
+            to ``label`` — a missing translation shows English rather than a
+            raw dotted key. Rows are rendered server-side, so the audit view
+            translates these before they reach the page.
+        table_name: ``__tablename__`` of the table these rows live in
+            (``"users_user"``), shown as the type tag beside the row's name.
+            Not derivable from ``entity_type`` in either direction, so the
+            module that owns the table states both. ``None`` falls back to the
+            class name.
+        label_resolver: Optional :data:`LabelResolver` naming individual rows.
+            Without it a reader gets a primary key and has to paste it into
+            another screen to learn which record changed; only the owning
+            module knows that a ``Setting`` is named by its key and a ``User``
+            by ``full_name or email``. Excluded from equality: it is typically
+            a closure, and two boots would build two unequal objects out of one
+            module — a registry conflict is about two modules claiming one
+            entity type, which the identity fields already express.
     """
 
     entity_type: str
     url_template: str
     label: str = ""
+    label_key: str = ""
+    table_name: str | None = None
+    label_resolver: LabelResolver | None = field(default=None, compare=False)
 
     def __post_init__(self) -> None:
-        if _ID_PLACEHOLDER not in self.url_template:
+        if self.url_template and _ID_PLACEHOLDER not in self.url_template:
             raise ValueError(
                 f"AuditLink for {self.entity_type!r} has url_template "
                 f"{self.url_template!r}, which contains no {_ID_PLACEHOLDER} — "
                 f"every row would link to the same page"
             )
 
-    def url_for(self, entity_id: str) -> str:
+    def url_for(self, entity_id: str) -> str | None:
+        """The row's page, or ``None`` when this kind of row has no screen."""
+        if not self.url_template:
+            return None
         return self.url_template.replace(_ID_PLACEHOLDER, entity_id)
 
 

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/diagnostics/__init__.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 from simple_module_core.diagnostics._i18n import I18nDiagnostics
 from simple_module_core.diagnostics._migration import MigrationDiagnostics
 from simple_module_core.diagnostics._module import ModuleDiagnostics
+from simple_module_core.diagnostics._pages import collect_tsx_pages
 from simple_module_core.diagnostics._runner import print_diagnostics, run_diagnostics
 from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
 
@@ -19,6 +20,7 @@ __all__ = [
     "I18nDiagnostics",
     "MigrationDiagnostics",
     "ModuleDiagnostics",
+    "collect_tsx_pages",
     "print_diagnostics",
     "run_diagnostics",
 ]

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/diagnostics/_pages.py

@@ -12,17 +12,62 @@ if TYPE_CHECKING:
     from simple_module_core.module import ModuleBase
 
 
+def _assignment(s: ast.stmt) -> tuple[ast.Name, ast.expr] | None:
+    """Return ``(target, value)`` for a single-target top-level assignment.
+
+    Covers both ``NAME = ...`` and the annotated ``NAME: Final = ...`` form
+    module constants are conventionally written in.
+    """
+    if isinstance(s, ast.Assign) and len(s.targets) == 1 and isinstance(s.targets[0], ast.Name):
+        return s.targets[0], s.value
+    if isinstance(s, ast.AnnAssign) and isinstance(s.target, ast.Name) and s.value is not None:
+        return s.target, s.value
+    return None
+
+
 def _module_level_str_consts(tree: ast.Module) -> dict[str, str]:
     """Return ``{name: literal}`` for top-level ``NAME = "string"`` assignments."""
-    return {
-        s.targets[0].id: s.value.value
-        for s in tree.body
-        if isinstance(s, ast.Assign)
-        and len(s.targets) == 1
-        and isinstance(s.targets[0], ast.Name)
-        and isinstance(s.value, ast.Constant)
-        and isinstance(s.value.value, str)
-    }
+    consts: dict[str, str] = {}
+    for s in tree.body:
+        assignment = _assignment(s)
+        if assignment is None:
+            continue
+        target, value = assignment
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            consts[target.id] = value.value
+    return consts
+
+
+def _resolve_fstring_consts(tree: ast.Module, consts: dict[str, str]) -> dict[str, str]:
+    """Resolve top-level ``NAME = f"{CONST}/lit"`` against already-known consts.
+
+    Only plain interpolations of known string constants count — a conversion,
+    format spec, or unknown name makes the value non-static, so it is skipped
+    rather than guessed at.
+    """
+    resolved: dict[str, str] = {}
+    for s in tree.body:
+        assignment = _assignment(s)
+        if assignment is None or not isinstance(assignment[1], ast.JoinedStr):
+            continue
+        target, value = assignment
+        parts: list[str] = []
+        for piece in value.values:
+            if isinstance(piece, ast.Constant) and isinstance(piece.value, str):
+                parts.append(piece.value)
+            elif (
+                isinstance(piece, ast.FormattedValue)
+                and isinstance(piece.value, ast.Name)
+                and piece.value.id in consts
+                and piece.conversion == -1
+                and piece.format_spec is None
+            ):
+                parts.append(consts[piece.value.id])
+            else:
+                break
+        else:
+            resolved[target.id] = "".join(parts)
+    return resolved
 
 
 def _iter_render_components(tree: ast.Module, consts: dict[str, str]) -> list[str]:
@@ -79,6 +124,19 @@ def find_render_calls(mod: ModuleBase, src_dir: Path) -> set[str]:
     consts: dict[str, str] = {}
     for tree in trees:
         consts.update(_module_level_str_consts(tree))
+    # Then f-string constants built from the plain ones above
+    # (``PAGE = f"{MODULE_NAME}/Browse"`` is the conventional shape). Repeat to
+    # a fixed point so a chain — ``PREFIX = f"{NAME}/sub"`` then
+    # ``PAGE = f"{PREFIX}/Browse"`` — resolves too; one pass would only learn
+    # the first hop and report the page as an SM003 orphan.
+    while True:
+        resolved: dict[str, str] = {}
+        for tree in trees:
+            resolved.update(_resolve_fstring_consts(tree, consts))
+        new = {k: v for k, v in resolved.items() if consts.get(k) != v}
+        if not new:
+            break
+        consts.update(new)
 
     prefix = f"{mod.meta.name}/"
     rendered: set[str] = set()

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/i18n.py

@@ -145,8 +145,18 @@ class I18nRegistry:
         # Plain-dict snapshots for serialization callers. ``dict(msgs)`` runs
         # once here rather than on every Inertia render. The public variant
         # (admin namespaces excluded) is what anonymous visitors receive.
-        self._message_snapshots = {locale: dict(msgs) for locale, msgs in self._messages.items()}
-        self._public_snapshots = public_messages
+        #
+        # Each non-default locale layers over the default one, so a key it has
+        # not translated yet resolves to the default language instead of
+        # reaching the browser missing. The client cannot recover on its own:
+        # i18next is initialised with ``fallbackLng`` equal to the active
+        # locale, so an absent key renders as the raw dotted key — a partially
+        # translated locale would put "dashboard.home.health" on screen. The
+        # server-side ``Translator`` has always fallen back this way; this
+        # makes the payload behave the same, and makes partial translations a
+        # safe, incremental state to be in.
+        self._message_snapshots = self._layered_snapshots(self._messages)
+        self._public_snapshots = self._layered_snapshots(public_messages)
         self._available_locales = tuple(locale for locale, msgs in self._messages.items() if msgs)
         self._available_locales_list = list(self._available_locales)
         self._loaded = True
@@ -162,6 +172,16 @@ class I18nRegistry:
             return self._available_locales_list
         return [locale for locale, msgs in self._messages.items() if msgs]
 
+    def _layered_snapshots(self, messages: dict[str, dict[str, str]]) -> dict[str, dict[str, str]]:
+        """Snapshot per locale, each layered over the default locale's."""
+        base = messages.get(self.default_locale, {})
+        return {
+            locale: dict(msgs)
+            if locale == self.default_locale
+            else {**base, **msgs}  # translated entries win; the rest read as default
+            for locale, msgs in messages.items()
+        }
+
     def messages(self, locale: str) -> Mapping[str, str]:
         """Flat dotted-key map for the given locale. Empty mapping if unknown.
 

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/menu.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import Literal
@@ -24,6 +25,15 @@ class MenuItem:
 
     label: str
     url: str
+    label_key: str = ""
+    """Catalog key for ``label``. Empty = ship ``label`` verbatim.
+
+    Menu labels are rendered on every page, so they are translated on the
+    server — the payload carries finished text and every render site (sidebar,
+    topbar, command palette) keeps working untouched. A key that resolves to
+    nothing falls back to ``label``, so a missing translation degrades to
+    English rather than to a raw dotted key on screen.
+    """
     icon: str = ""
     order: int = 0
     section: MenuSection = MenuSection.SIDEBAR
@@ -42,6 +52,14 @@ class MenuItem:
     method: MenuItemMethod = "get"
     """HTTP method used when the item is activated. ``"post"`` renders as an
     Inertia form submission so the target endpoint can be POST-only (e.g. logout)."""
+    group_key: str = ""
+    """Catalog key for ``group``, with the same fallback rule as ``label_key``.
+
+    Group headers are shared vocabulary — several modules file entries under
+    "Administration" — so they live in the ``ui`` namespace. Letting each
+    module invent its own key would let one translation drift from another and
+    split a single header in two.
+    """
     group: str = ""
     """Sidebar group label. Empty = ungrouped (renders flat, no header).
     Items in the same section that share a group are visually clustered under a
@@ -79,6 +97,7 @@ class MenuRegistry:
         is_authenticated: bool,
         roles: list[str] | None = None,
         permissions: list[str] | None = None,
+        translate: Callable[[str], str] | None = None,
     ) -> dict[str, list[dict]]:
         """Return menu items grouped by section, filtered by auth/roles/permissions.
 
@@ -86,12 +105,25 @@ class MenuRegistry:
         wildcards). Items declaring permissions the caller lacks are dropped,
         so the sidebar never offers a screen that will 403 on click.
 
+        ``translate`` resolves ``label_key``/``group_key`` against the request's
+        locale. Omitting it (or omitting the keys) ships the literal ``label``
+        and ``group``, which is what third-party modules predating the keys do.
+
         Returns a dict ready to be serialized into Inertia shared props.
         """
         roles = roles or []
         granted = set(permissions or [])
         result: dict[str, list[dict]] = {s.value: [] for s in MenuSection}
 
+        def render(key: str, fallback: str) -> str:
+            # Translator.t() echoes the key back when the catalog has no entry.
+            # Showing "users.nav.users" in the sidebar would be worse than the
+            # English it replaced, so an unresolved key keeps the literal.
+            if not key or translate is None:
+                return fallback
+            translated = translate(key)
+            return fallback if translated == key else translated
+
         for item in self.all_items:
             if item.requires_auth and not is_authenticated:
                 continue
@@ -103,11 +135,11 @@ class MenuRegistry:
                 continue
             result[item.section.value].append(
                 {
-                    "label": item.label,
+                    "label": render(item.label_key, item.label),
                     "url": item.url,
                     "icon": item.icon,
                     "method": item.method,
-                    "group": item.group,
+                    "group": render(item.group_key, item.group),
                 }
             )
 

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/module.py

@@ -1,12 +1,13 @@
-"""Module base class and metadata."""
+"""Module lifecycle base class. ``ModuleMeta`` lives in ``module_meta``."""
 
 from __future__ import annotations
 
 from abc import ABC
-from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from simple_module_core.module_meta import ModuleMeta
+
 if TYPE_CHECKING:
     from fastapi import APIRouter, FastAPI
 
@@ -19,33 +20,7 @@ if TYPE_CHECKING:
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
     from simple_module_core.public_routes import PublicRouteRegistry
-
-
-@dataclass(frozen=True)
-class ModuleMeta:
-    """Metadata describing a module."""
-
-    name: str
-    route_prefix: str = ""
-    view_prefix: str = ""
-    depends_on: list[str] = field(default_factory=list)
-    version: str = "1.0.0"
-    requires_framework: str | None = None
-    """PEP 440 specifier for the framework API version this module supports.
-
-    Example: ``">=1.0,<2.0"``. When set, the module is rejected at boot if the
-    installed ``simple_module_core.FRAMEWORK_API_VERSION`` does not satisfy it.
-    When ``None``, no compatibility check is performed (legacy modules).
-    """
-    i18n_audience: str = "public"
-    """Who this module's locale catalog is shipped to: ``"public"`` or ``"admin"``.
-
-    ``"public"`` (the default) ships the catalog in every Inertia payload.
-    ``"admin"`` ships it only to authenticated users — declare it on modules
-    whose UI sits entirely behind login (settings, permissions, dashboards) so
-    anonymous visitors don't download admin form labels on every public page.
-    The catalog is always available server-side (``Translator``) either way.
-    """
+    from simple_module_core.setup_steps import SetupRegistry
 
 
 class ModuleBase(ABC):
@@ -111,6 +86,19 @@ class ModuleBase(ABC):
     ) -> None:
         """Register API endpoints and Inertia view routes."""
 
+    def register_admin_routes(self, admin_router: APIRouter) -> None:
+        """Register admin-only view routes, mounted at ``meta.admin_view_prefix``.
+
+        Only needed by modules that serve both public and administrative
+        pages — see ``ModuleMeta.admin_view_prefix``. A module whose views are
+        all administrative should point ``view_prefix`` at ``/admin/...`` and
+        keep using ``register_routes``.
+
+        Nothing here is gated automatically: the prefix is a URL convention,
+        not a permission. Guard these routes with the same dependencies you
+        would use anywhere else.
+        """
+
     def register_menu_items(self, registry: MenuRegistry) -> None:
         """Contribute menu items visible in the UI."""
 
@@ -131,6 +119,20 @@ class ModuleBase(ABC):
     def register_health_checks(self, registry: HealthRegistry) -> None:
         """Contribute health checks for the ``/health/ready`` endpoint."""
 
+    def register_setup_steps(self, registry: SetupRegistry) -> None:
+        """Declare what this module needs before the install is usable.
+
+        While any required step reports incomplete, ``SetupMiddleware`` serves
+        the first-run wizard instead of the app::
+
+            registry.add(SetupStep(id="users.administrator", ...))
+
+        A module that registers nothing never gates the app — that is how an
+        external identity provider opts out. See docs/module-authoring.md.
+
+        Called once at boot, in dependency order.
+        """
+
     def register_public_routes(self, registry: PublicRouteRegistry) -> None:
         """Declare routes that must bypass authentication (anonymous access).
 
@@ -272,3 +274,6 @@ class ModuleBase(ABC):
 
     async def on_shutdown(self, app: FastAPI) -> None:
         """Called during app shutdown."""
+
+
+__all__ = ["ModuleBase", "ModuleMeta"]

simple_module_core-0.0.33/simple_module_core/module_meta.py

@@ -0,0 +1,53 @@
+"""Module metadata — the declarative half of a module definition.
+
+Split from ``module.py`` so that file holds only the lifecycle base class.
+``ModuleMeta`` is what a module *declares* about itself (name, mount
+points, dependencies, compatibility); ``ModuleBase`` is what it *does*.
+They change for different reasons and are read by different callers —
+discovery reads the metadata, the host invokes the hooks.
+
+Re-exported from ``module.py``, so every existing import still works.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ModuleMeta:
+    """Metadata describing a module."""
+
+    name: str
+    route_prefix: str = ""
+    view_prefix: str = ""
+    admin_view_prefix: str = ""
+    """Mount point for admin-only view routes, e.g. ``"/admin/users"``.
+
+    A module gets exactly one ``view_prefix``, which is a problem for modules
+    that are only *partly* administrative: ``users`` serves ``/users/login``
+    and the user-management CRUD from the same package, and those belong in
+    different places in the URL space. Declaring this gives such a module a
+    second view router mounted here, populated by ``register_admin_routes``.
+
+    Modules that are administrative end to end don't need it — they just point
+    ``view_prefix`` at ``/admin/...`` directly.
+    """
+    depends_on: list[str] = field(default_factory=list)
+    version: str = "1.0.0"
+    requires_framework: str | None = None
+    """PEP 440 specifier for the framework API version this module supports.
+
+    Example: ``">=1.0,<2.0"``. When set, the module is rejected at boot if the
+    installed ``simple_module_core.FRAMEWORK_API_VERSION`` does not satisfy it.
+    When ``None``, no compatibility check is performed (legacy modules).
+    """
+    i18n_audience: str = "public"
+    """Who this module's locale catalog is shipped to: ``"public"`` or ``"admin"``.
+
+    ``"public"`` (the default) ships the catalog in every Inertia payload.
+    ``"admin"`` ships it only to authenticated users — declare it on modules
+    whose UI sits entirely behind login (settings, permissions, dashboards) so
+    anonymous visitors don't download admin form labels on every public page.
+    The catalog is always available server-side (``Translator``) either way.
+    """

{simple_module_core-0.0.32 → simple_module_core-0.0.33}/simple_module_core/permissions.py

@@ -6,13 +6,26 @@ from dataclasses import dataclass, field
 
 WILDCARD = "*"
 
+ADMIN_ROLE = "admin"
+"""The one role name the framework itself knows.
+
+Everything else about roles is module-owned, but the framework needs this to
+resolve the wildcard grant below and to decide who can still reach the app
+while maintenance mode is on.
+"""
+
 # Default role→permission mapping. Admin gets all permissions via the wildcard.
 # Additional mappings are added at registration time via PermissionRegistry.map_role.
 DEFAULT_ROLE_PERMISSIONS: dict[str, list[str]] = {
-    "admin": [WILDCARD],
+    ADMIN_ROLE: [WILDCARD],
 }
 
 
+def is_admin(roles: list[str] | None) -> bool:
+    """Whether ``roles`` carries the framework's admin role."""
+    return bool(roles) and ADMIN_ROLE in roles
+
+
 @dataclass
 class PermissionGroup:
     """A named group of related permissions (typically one per module)."""
@@ -111,7 +124,7 @@ class PermissionRegistry:
         other roles get none. Override for richer mapping.
         """
         if role_permission_map is None:
-            if "admin" in roles:
+            if is_admin(roles):
                 return set(self.all_permissions)
             return set()
 

simple_module_core-0.0.33/simple_module_core/redirect_safety.py

@@ -0,0 +1,78 @@
+"""Safety net for user-influenced redirect targets.
+
+Several flows park "where the visitor was heading" somewhere a browser can
+reach — ``AuthMiddleware`` stashes it in the session before bouncing an
+anonymous visitor to login, ``site_lock`` puts it in the unlock page's query
+string. Anything replayed into a ``Location`` header is an open-redirect
+surface, so every producer and consumer funnels through :func:`safe_next`.
+
+This lives in the framework rather than in whichever module needed it first:
+it encodes no plugin knowledge, and duplicating URL-safety rules per module is
+how one copy ends up missing a case.
+"""
+
+from __future__ import annotations
+
+DEFAULT_FALLBACK = "/"
+
+SESSION_NEXT_KEY = "next"
+"""Session key holding the post-login destination.
+
+This is the contract between ``AuthMiddleware`` (which writes it when it
+bounces an anonymous visitor) and whichever provider completes the login and
+sends the visitor onward. It is shared rather than redeclared per module
+because a provider that reads a *different* key silently loses every deep
+link — which is exactly how the local provider drifted from the Keycloak one.
+"""
+
+
+def safe_next(raw: str | None, *, fallback: str = DEFAULT_FALLBACK) -> str:
+    """Return ``raw`` if it is a same-site absolute path, else ``fallback``.
+
+    Rejects protocol-relative (``//host``) and backslash-prefixed (``/\\host``)
+    targets — browsers resolve both off-site — plus anything carrying CR/LF,
+    which could otherwise be smuggled into the redirect header.
+    """
+    if not raw or not raw.startswith("/"):
+        return fallback
+    if raw.startswith(("//", "/\\")):
+        return fallback
+    if "\r" in raw or "\n" in raw:
+        return fallback
+    return raw
+
+
+def safe_next_or_none(raw: str | None) -> str | None:
+    """Like :func:`safe_next`, but ``None`` when ``raw`` is unusable.
+
+    Callers that fall back to a *configured* destination (rather than ``/``)
+    need to tell "no target" apart from "the target was ``/``" — returning the
+    fallback would silently outrank a configured ``login_redirect_url``.
+    """
+    result = safe_next(raw, fallback="")
+    return result or None
+
+
+def non_empty_redirect(value: str, *, default: str) -> str:
+    """Normalise a configured redirect destination, never returning ``""``.
+
+    Any auth provider can expose a ``login_redirect_url``-style setting, and
+    nothing stops an admin clearing it in the generic module-settings editor.
+    Every consumer treats the value as a destination — Inertia's
+    ``router.visit("")`` silently reloads the current page, and an empty
+    ``Location`` header is a broken redirect — so providers normalise on their
+    settings class, where hydration and ``apply_changes_and_reload`` both run.
+    It lives here rather than in one provider because the providers must not
+    import each other (cross-module coupling), and this is the same concern as
+    the rest of this module.
+    """
+    return value.strip() or default
+
+
+__all__ = [
+    "DEFAULT_FALLBACK",
+    "SESSION_NEXT_KEY",
+    "non_empty_redirect",
+    "safe_next",
+    "safe_next_or_none",
+]