simple-module-hosting 0.0.37__tar.gz → 0.0.38__tar.gz

{simple_module_hosting-0.0.37 → simple_module_hosting-0.0.38}/.gitignore

@@ -7,8 +7,6 @@ build/
 .venv/
 *.egg
 
-# UV
-uv.lock
 
 # Node
 node_modules/
@@ -65,3 +63,4 @@ host/client_app/.playwright-cli/*
 .qa/
 .verify/
 /openapi.json
+qa-shots/

{simple_module_hosting-0.0.37 → simple_module_hosting-0.0.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_hosting
-Version: 0.0.37
+Version: 0.0.38
 Summary: FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -22,18 +22,20 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
-Requires-Dist: fastapi>=0.115
+Requires-Dist: fastapi<0.157,>=0.140
 Requires-Dist: httpx>=0.27
 Requires-Dist: itsdangerous>=2.0
 Requires-Dist: jinja2>=3.1
-Requires-Dist: simple-module-core==0.0.37
-Requires-Dist: simple-module-db==0.0.37
-Requires-Dist: simple-module-inertia==0.0.37
+Requires-Dist: simple-module-core==0.0.38
+Requires-Dist: simple-module-db==0.0.38
+Requires-Dist: simple-module-inertia==0.0.38
 Requires-Dist: starlette>=0.44
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn[standard]>=0.34
 Provides-Extra: redis
 Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk[celery,fastapi]<3,>=2.20; extra == 'sentry'
 Description-Content-Type: text/markdown
 
 # simple_module_hosting

{simple_module_hosting-0.0.37 → simple_module_hosting-0.0.38}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_hosting"
-version = "0.0.37"
+version = "0.0.38"
 description = "FastAPI + Inertia.js host runtime for simple_module — app_builder, middleware stack, CLI (sm / simple-module), scaffolding"
 readme = "README.md"
 license = "MIT"
@@ -22,16 +22,16 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.1",
-    "fastapi>=0.115",
+    "fastapi>=0.140,<0.157",
     "httpx>=0.27",
     # SessionMiddleware (starlette.middleware.sessions) imports itsdangerous at
     # module import time; starlette treats it as an optional extra, so declare
     # it directly — out-of-tree hosts have nothing else pulling it in.
     "itsdangerous>=2.0",
     "jinja2>=3.1",
-    "simple_module_core==0.0.37",
-    "simple_module_db==0.0.37",
-    "simple_module_inertia==0.0.37",
+    "simple_module_core==0.0.38",
+    "simple_module_db==0.0.38",
+    "simple_module_inertia==0.0.38",
     "starlette>=0.44",
     "tomlkit>=0.13",
     "uvicorn[standard]>=0.34",
@@ -40,6 +40,8 @@ dependencies = [
 [project.optional-dependencies]
 # Shared rate-limiter store (SM_REDIS_URL). Without it the limiter counts per worker.
 redis = ["redis>=5"]
+# Error reporting (SM_SENTRY_DSN). Never imported unless the DSN is set.
+sentry = ["sentry-sdk[fastapi,celery]>=2.20,<3"]
 
 [project.scripts]
 sm-host = "simple_module_hosting.host_cli:app"

simple_module_hosting-0.0.38/simple_module_hosting/_api_version.py

@@ -0,0 +1,37 @@
+"""Default ``HostSettings.api_version``: the host project's own version."""
+
+from __future__ import annotations
+
+
+def default_api_version() -> str:
+    """The host project's version, else ``0.0.0``.
+
+    This repo's host is the installed ``simple-module-host`` distribution. A
+    scaffolded host is ``package = false`` (never installed), so there is no
+    distribution to ask: read ``[project].version`` from its ``pyproject.toml``
+    under ``SM_PROJECT_ROOT`` (or the cwd) instead.
+    """
+    import tomllib
+    from importlib.metadata import PackageNotFoundError, version
+
+    from simple_module_core.dotenv import find_env_file
+
+    try:
+        return version("simple-module-host")
+    except PackageNotFoundError:
+        pass
+    # Same project-root convention as .env (SM_PROJECT_ROOT, else a bounded walk
+    # up from the cwd), so a CLI run from host/ finds the same project as the app.
+    root = find_env_file().parent
+    for candidate in (root / "host" / "pyproject.toml", root / "pyproject.toml"):
+        try:
+            project = tomllib.loads(candidate.read_text(encoding="utf-8")).get("project")
+        except (OSError, ValueError):  # missing/unreadable, bad UTF-8, bad TOML
+            continue
+        if not isinstance(project, dict):
+            continue
+        # The first file declaring a [project] is the host's: a dynamic version
+        # must not fall through to an unrelated (workspace-root) project's.
+        found = project.get("version")
+        return found if isinstance(found, str) and found else "0.0.0"
+    return "0.0.0"

simple_module_hosting-0.0.38/simple_module_hosting/_app_boot.py

@@ -0,0 +1,107 @@
+"""Boot-phase helpers for ``create_app``: app construction, database init, static mount."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from fastapi import Depends, FastAPI
+from simple_module_core.design_packs import DesignPackRegistry
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_core.health import HealthRegistry
+from simple_module_core.menu import MenuRegistry
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.public_routes import PublicRouteRegistry
+from simple_module_db.listeners import register_listeners
+from simple_module_db.session import init_db
+
+from simple_module_hosting._db_health import register_database_check
+from simple_module_hosting._openapi import (
+    API_OPENAPI_URL,
+    install_openapi_filter,
+    make_unique_id_function,
+    openapi_served,
+)
+from simple_module_hosting._process_services import configure_process_services
+from simple_module_hosting.db_options import database_options
+from simple_module_hosting.settings import Settings
+from simple_module_hosting.static_files import PrecompressedStaticFiles
+from simple_module_hosting.token_guard import token_route_guard
+
+logger = logging.getLogger("simple_module_hosting.app_builder")
+
+_DOCS_URL = "/api/docs"
+_REDOC_URL = "/api/redoc"
+_STATIC_MOUNT_PATH = "/static"
+_STATIC_DIR_NAME = "static"
+
+
+def build_fastapi_app(settings: Settings, lifespan) -> FastAPI:
+    serve_openapi = openapi_served(
+        is_development=settings.is_development, openapi_public=settings.openapi_public
+    )
+    app = FastAPI(
+        title=settings.api_title,
+        version=settings.api_version,
+        description=settings.api_description,
+        openapi_url=API_OPENAPI_URL if serve_openapi else None,
+        generate_unique_id_function=make_unique_id_function(),
+        docs_url=_DOCS_URL if settings.is_development else None,
+        redoc_url=_REDOC_URL if settings.is_development else None,
+        lifespan=lifespan,
+        # API tokens reach only permission-gated, non-page routes (or ones
+        # marked ``TokenAllowed``); see ``token_guard``.
+        dependencies=[Depends(token_route_guard)],
+    )
+
+    install_openapi_filter(app)  # AuthMiddleware reads openapi_url: anonymous iff served
+    app.state.openapi_url = API_OPENAPI_URL if serve_openapi else None
+    return app
+
+
+def log_registration_summary(
+    menu_registry: MenuRegistry,
+    perm_registry: PermissionRegistry,
+    ff_registry: FeatureFlagRegistry,
+    health_registry: HealthRegistry,
+    public_route_registry: PublicRouteRegistry,
+    design_pack_registry: DesignPackRegistry,
+) -> None:
+    logger.info(
+        "Registered %d menu items, %d permissions, %d feature flags, "
+        "%d health checks, %d public routes, %d design packs",
+        len(menu_registry.all_items),
+        len(perm_registry.all_permissions),
+        len(ff_registry.all_flags),
+        len(health_registry.all_checks),
+        len(public_route_registry.routes),
+        len(design_pack_registry.all()),
+    )
+
+
+def init_database(settings: Settings, health_registry: HealthRegistry):
+    db_state = init_db(
+        settings.database_url,
+        echo=settings.debug,
+        **database_options(settings),
+    )
+    # Multi-tenant installs fail closed: a tenant-scoped query with no tenant
+    # context raises instead of reading every tenant's rows.
+    db_state.tenant_strict = settings.multi_tenant
+    # Where unbound / all_tenants() writes land on a single-tenant install:
+    # its ``default_tenant`` when set, so they stay visible to its requests.
+    if not settings.multi_tenant and settings.default_tenant:
+        db_state.default_tenant_id = settings.default_tenant
+    register_listeners(db_state)
+    configure_process_services(settings.redis_url, engine=db_state.engine)
+    # The host's own readiness signal, and the only probe-safe check in a
+    # default install — module checks reach third parties and are on-demand.
+    register_database_check(health_registry, db_state)
+    return db_state
+
+
+def mount_host_static(app: FastAPI, project_root: Path) -> None:
+    static_dir = project_root / "host" / _STATIC_DIR_NAME
+    if static_dir.is_dir():
+        static = PrecompressedStaticFiles(directory=static_dir)
+        app.mount(_STATIC_MOUNT_PATH, static, name=_STATIC_DIR_NAME)

{simple_module_hosting-0.0.37 → simple_module_hosting-0.0.38}/simple_module_hosting/_boot_checks.py

@@ -1,5 +1,8 @@
 """Diagnostics that need the built app, so cannot run from ``make doctor``.
 
+SM025 runs in every environment; SM031 (an unguarded ``/api`` route) needs the
+finished route table, so it runs at the end of a development boot only.
+
 The module diagnostics in Phase 2 see only module classes and the source tree.
 A check about what modules *registered* has to wait until after Phase 5, and
 unlike the source-tree checks it is meaningful in production too.
@@ -12,6 +15,8 @@ from typing import TYPE_CHECKING, Any
 
 from simple_module_core.diagnostics import Diagnostic, check_tenant_resolver, print_diagnostics
 
+from simple_module_hosting._route_access import check_unguarded_api_routes
+
 if TYPE_CHECKING:
     from fastapi import FastAPI
     from simple_module_core.services import DiagnosticsState
@@ -44,4 +49,16 @@ def report_tenant_resolution(
     return found
 
 
-__all__ = ["report_tenant_resolution"]
+def report_unguarded_routes(app: FastAPI, diagnostics_state: DiagnosticsState) -> list[Diagnostic]:
+    """SM031 (dev boot only; needs the finished route table): print and fold into Doctor."""
+    found = check_unguarded_api_routes(app)
+    if found:
+        print_diagnostics(found)
+    runner = diagnostics_state.runner
+    if runner is not None:
+        diagnostics_state.runner = lambda: [*runner(), *check_unguarded_api_routes(app)]
+        diagnostics_state.results = [*diagnostics_state.results, *found]
+    return found
+
+
+__all__ = ["report_tenant_resolution", "report_unguarded_routes"]

simple_module_hosting-0.0.38/simple_module_hosting/_cors.py

@@ -0,0 +1,76 @@
+"""CORS dispatch (#527).
+
+One Starlette ``CORSMiddleware`` is built per distinct :class:`CorsPolicy`; each
+request is routed to the one whose policy the registry matches for its method and
+path (most specific wins). A request no policy covers passes through untouched,
+so a path nobody opted in never gains CORS headers.
+
+Installed between RequestLogging and BodyLimit, so a preflight is answered before
+auth, rate limit, setup or maintenance can reject it, and a 413 from BodyLimit
+still carries the CORS headers the browser needs to read it.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.cors import CorsPolicy, CorsPolicyRegistry
+from starlette.middleware.cors import CORSMiddleware
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from simple_module_hosting.host_settings import HostSettings
+
+
+def host_policy(settings: HostSettings) -> CorsPolicy | None:
+    """The ``/api/`` policy from ``cors_*`` settings; ``None`` when no origin is set."""
+    # Every field is read even when unset: they are restart-required, and the
+    # build-time-settings guard learns that from the reads.
+    fields = (
+        settings.cors_allow_origins,
+        settings.cors_allow_credentials,
+        settings.cors_allow_methods,
+        settings.cors_allow_headers,
+        settings.cors_expose_headers,
+        settings.cors_max_age,
+    )
+    origins, credentials, methods, headers, expose, max_age = fields
+    if not origins:
+        return None
+    return CorsPolicy(
+        origins=tuple(origins),
+        allow_credentials=credentials,
+        methods=tuple(methods),
+        headers=tuple(headers),
+        expose_headers=tuple(expose),
+        max_age=max_age,
+    )
+
+
+class CorsMiddleware:
+    def __init__(self, app: ASGIApp, *, registry: CorsPolicyRegistry) -> None:
+        self.app = app
+        self.registry = registry
+        self._handlers: dict[CorsPolicy, ASGIApp] = {}
+
+    def _handler(self, policy: CorsPolicy) -> ASGIApp:
+        handler = self._handlers.get(policy)
+        if handler is None:
+            handler = CORSMiddleware(
+                self.app,
+                allow_origins=list(policy.origins),
+                allow_credentials=policy.allow_credentials,
+                allow_methods=list(policy.methods),
+                allow_headers=list(policy.headers),
+                expose_headers=list(policy.expose_headers),
+                max_age=policy.max_age,
+            )
+            self._handlers[policy] = handler
+        return handler
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or len(self.registry) == 0:
+            await self.app(scope, receive, send)
+            return
+        policy = self.registry.match(scope["method"], scope["path"])
+        if policy is None:
+            await self.app(scope, receive, send)
+            return
+        await self._handler(policy)(scope, receive, send)

{simple_module_hosting-0.0.37 → simple_module_hosting-0.0.38}/simple_module_hosting/_error_handlers.py

@@ -10,6 +10,7 @@ from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 from simple_module_core.exceptions import NotFoundError
+from simple_module_core.permission_denied import PermissionDenied
 from simple_module_inertia import (
     Inertia,
     InertiaConfig,
@@ -22,7 +23,6 @@ from starlette.responses import Response
 
 from simple_module_hosting._inertia_shared import _INERTIA_HEADER
 from simple_module_hosting._observability import CorrelationIdMiddleware
-from simple_module_hosting.permissions import PERMISSION_DENIED_PREFIX
 
 logger = logging.getLogger(__name__)
 
@@ -55,26 +55,6 @@ def _specific_detail(status_code: int, message: str) -> str:
     return "" if message.strip().casefold() == phrase.casefold() else message
 
 
-def _required_permission(message: str) -> str | None:
-    """The permission named by a ``RequiresPermission`` denial, if this is one.
-
-    The 403 page says "Your role doesn't include ``<perm>``. Ask an admin to
-    grant it." — it needs the bare permission name, not the sentence the guard
-    wrote for logs and API clients. Reading it back off the detail (using the
-    guard's own exported prefix) keeps ``RequiresPermission`` as the single
-    place that knows the name; the alternative, stashing it on
-    ``request.state``, only works when the exception travels the one code path
-    that set it, and 403s are also raised by hand.
-
-    Anything else — a role-gated ``/admin`` 403, a hand-raised
-    ``HTTPException(403, "Administrator access required")`` — yields ``None``,
-    and the page falls back to copy that names no permission.
-    """
-    if not message.startswith(PERMISSION_DENIED_PREFIX):
-        return None
-    return message[len(PERMISSION_DENIED_PREFIX) :].strip() or None
-
-
 def _login_url(request: Request) -> str | None:
     """Best-effort login URL for the sign-in statuses.
 
@@ -159,9 +139,13 @@ async def render_error_page(
     status_code: int,
     message: str,
     headers: Mapping[str, str] | None = None,
+    required_permission: str | None = None,
 ) -> Response:
     """Render the Inertia error page for *status_code*.
 
+    ``required_permission`` names the permission a 403 lacked (from
+    :class:`PermissionDenied`); the page words its own sentence around it.
+
     ``headers`` carries an ``HTTPException``'s own headers through to the
     response. A rendered page is still the same status as the JSON body it
     replaces, so ``WWW-Authenticate`` on a 401 and ``Retry-After`` on a
@@ -208,7 +192,7 @@ async def render_error_page(
                 # Always present, null when no permission is involved: the page
                 # branches on it, and an absent prop is indistinguishable there
                 # from one that was never wired.
-                "required_permission": _required_permission(message),
+                "required_permission": required_permission,
                 "login_url": (_login_url(request) if status_code in _SIGN_IN_STATUSES else None),
                 # Set by MaintenanceMiddleware. A planned outage reads very
                 # differently from the same status code arriving unbidden.
@@ -249,7 +233,8 @@ async def http_exception_handler(request: Request, exc: HTTPException) -> Respon
     headers = getattr(exc, "headers", None)
     if exc.status_code in _INERTIA_ERROR_STATUSES and not _wants_json(request):
         detail = str(exc.detail) if exc.detail else ""
-        return await render_error_page(request, exc.status_code, detail, headers)
+        required = exc.permission if isinstance(exc, PermissionDenied) else None
+        return await render_error_page(request, exc.status_code, detail, headers, required)
     return JSONResponse(
         status_code=exc.status_code,
         content={"detail": exc.detail},

simple_module_hosting-0.0.38/simple_module_hosting/_forwarded_host.py

@@ -0,0 +1,135 @@
+"""Honour ``X-Forwarded-Host`` from a trusted proxy, for allowlisted hosts only (#528).
+
+uvicorn's ``ProxyHeadersMiddleware`` corrects scheme and client address but not
+the host, so behind a proxy that rewrites ``Host`` to the upstream name,
+``request.url_for(...)`` and the tenants subdomain resolver see the internal
+name. This middleware swaps the ``host`` header (and ``scope["server"]``) for the
+forwarded one, but only when the peer is a trusted proxy *and* the value is on
+the operator's allowlist: an unlisted host is ignored, so a forged header cannot
+poison absolute URLs or pick a tenant.
+
+It runs before ProxyHeaders (which replaces ``scope["client"]`` with the
+forwarded client) so the peer it checks is still the proxy's TCP address.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import re
+from collections.abc import Iterable
+
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+logger = logging.getLogger(__name__)
+
+_WILDCARD = "*"
+_SUBDOMAIN_PREFIX = "*."
+_HOST_HEADER = b"host"
+_FORWARDED_HOST_HEADER = b"x-forwarded-host"
+_FORWARDED_PROTO_HEADER = b"x-forwarded-proto"
+_DEFAULT_PORTS = {"https": 443, "wss": 443}
+_FALLBACK_PORT = 80
+_HOST_PATTERN = re.compile(r"^(?P<host>[a-z0-9]([a-z0-9._-]*[a-z0-9])?)(:(?P<port>\d{1,5}))?$")
+
+
+def _split_host(value: str) -> tuple[str, str | None] | None:
+    match = _HOST_PATTERN.match(value.strip().lower())
+    return (match["host"], match["port"]) if match else None
+
+
+def _forwarded_proto(scope: Scope) -> str | None:
+    """Rightmost ``X-Forwarded-Proto``: ProxyHeaders has not rewritten the scheme yet."""
+    raw = ",".join(v.decode("latin-1") for k, v in scope["headers"] if k == _FORWARDED_PROTO_HEADER)
+    return raw.split(",")[-1].strip().lower() or None
+
+
+class TrustedPeers:
+    """Mirror of uvicorn's trusted-hosts rule: ``*``, IPs and CIDRs, comma-separated."""
+
+    def __init__(self, spec: str) -> None:
+        self._always = spec.strip() == _WILDCARD
+        self._literals: set[str] = set()
+        self._networks: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
+        for item in spec.split(","):
+            item = item.strip()
+            if not item or item == _WILDCARD:
+                continue
+            try:
+                self._networks.append(ipaddress.ip_network(item, strict=False))
+            except ValueError:
+                self._literals.add(item)  # e.g. a unix-socket peer name
+
+    def __contains__(self, peer: str | None) -> bool:
+        if self._always:
+            return True
+        if not peer:
+            return False
+        if peer in self._literals:
+            return True
+        try:
+            address = ipaddress.ip_address(peer)
+        except ValueError:
+            return False
+        return any(address in network for network in self._networks)
+
+
+class HostAllowlist:
+    """Exact hosts or ``*.example.com`` (any depth, never the apex), optional port."""
+
+    def __init__(self, entries: Iterable[str]) -> None:
+        self._exact: list[tuple[str, str | None]] = []
+        self._suffixes: list[tuple[str, str | None]] = []
+        for entry in entries:
+            wildcard = entry.strip().lower().startswith(_SUBDOMAIN_PREFIX)
+            parsed = _split_host(entry.strip()[len(_SUBDOMAIN_PREFIX) :] if wildcard else entry)
+            if parsed is None:
+                logger.warning("Ignoring invalid forwarded_host_allowlist entry %r", entry)
+                continue
+            host, port = parsed
+            (self._suffixes if wildcard else self._exact).append((host, port))
+
+    def allows(self, host: str, port: str | None) -> bool:
+        def port_ok(allowed: str | None) -> bool:
+            return allowed is None or allowed == port
+
+        if any(host == name and port_ok(p) for name, p in self._exact):
+            return True
+        return any(host.endswith("." + name) and port_ok(p) for name, p in self._suffixes)
+
+
+class ForwardedHostMiddleware:
+    def __init__(self, app: ASGIApp, *, trusted_hosts: str, allowlist: Iterable[str]) -> None:
+        self.app = app
+        self._peers = TrustedPeers(trusted_hosts)
+        self._allowed = HostAllowlist(allowlist)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] in ("http", "websocket"):
+            client = scope.get("client")
+            if client and client[0] in self._peers:
+                self._rewrite(scope)
+        await self.app(scope, receive, send)
+
+    def _rewrite(self, scope: Scope) -> None:
+        raw = ",".join(
+            v.decode("latin-1") for k, v in scope["headers"] if k == _FORWARDED_HOST_HEADER
+        )
+        if not raw:
+            return
+        # Rightmost value: the one our trusted proxy added. Earlier values came
+        # from upstream hops or the client and cannot be trusted (an appending
+        # proxy keeps whatever the client sent at the front).
+        parsed = _split_host(raw.split(",")[-1])
+        if parsed is None or not self._allowed.allows(*parsed):
+            logger.debug("Ignoring X-Forwarded-Host %r: not on the allowlist", raw)
+            return
+        host, port = parsed
+        value = host if port is None else f"{host}:{port}"
+        scope["headers"] = [
+            *((k, v) for k, v in scope["headers"] if k != _HOST_HEADER),
+            (_HOST_HEADER, value.encode("latin-1")),
+        ]
+        proto = _forwarded_proto(scope) or scope.get("scheme", "")
+        default = _DEFAULT_PORTS.get(proto, _FALLBACK_PORT)
+        scope["server"] = (host, int(port) if port else default)

simple_module_hosting-0.0.38/simple_module_hosting/_host_settings_support.py

@@ -0,0 +1,108 @@
+"""Restart-required markers and validator bodies for :class:`HostSettings`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic_core import PydanticCustomError
+from simple_module_core.cors import WILDCARD as CORS_WILDCARD
+from simple_module_core.discovery import DEFAULT_AUTH_PROVIDER
+from simple_module_core.stored_settings import RELATED_FIELDS_CTX
+
+if TYPE_CHECKING:
+    from simple_module_hosting.host_settings import HostSettings
+
+# Marks a field the running process cannot pick up without a restart, so the
+# admin UI can say so rather than letting the edit look like it took effect.
+_RESTART_DB = {"requires_restart": True, "group": "Database"}
+_RESTART_GUARD = {"requires_restart": True, "group": "Request guards"}
+_RESTART_CORS = {"requires_restart": True, "group": "CORS"}
+_RESTART_API = {"requires_restart": True, "group": "API"}
+
+# Consumed while create_app builds the tenant middleware, the strict tenant
+# filter, the i18n registry and LocaleMiddleware, the auth provider and the
+# public-route registry, the proxy middleware and logging — none of which the
+# lifespan hydration can rebuild (#499). test_build_time_settings_marked keeps
+# this in step with what create_app actually reads.
+_RESTART_TENANCY = {"requires_restart": True, "group": "Tenancy"}
+_RESTART_I18N = {"requires_restart": True, "group": "Localization"}
+_RESTART_AUTH = {"requires_restart": True, "group": "Authentication"}
+_RESTART_LOGGING = {"requires_restart": True, "group": "Logging"}
+_RESTART_SECURITY = {"requires_restart": True, "group": "Security"}
+
+
+def check_public_base_url(value: str) -> str:
+    from urllib.parse import urlsplit
+
+    value = value.strip().rstrip("/")
+    parts = urlsplit(value)
+    if value and not (parts.scheme in ("http", "https") and parts.netloc):
+        raise ValueError("public_base_url must be an http(s) origin such as https://example.org")
+    return value
+
+
+def check_rate(value: str) -> str:
+    from simple_module_core.rate_limit import parse_rate
+
+    parse_rate(value)  # raises RateLimitError (a ValueError) on a typo
+    return value.strip()
+
+
+def check_native_prefixes(value: list[str]) -> list[str]:
+    cleaned = [prefix.strip() for prefix in value]
+    for prefix in cleaned:
+        if not prefix.startswith("/"):
+            raise ValueError(f"native_link_prefixes entry {prefix!r} must start with '/'")
+    return cleaned
+
+
+def check_body_bytes(value: int) -> int:
+    if value < 0:
+        raise ValueError("max_request_body_bytes must be >= 0 (0 disables the guard)")
+    return value
+
+
+def normalize_auth_provider(value: str) -> str:
+    return value.strip() or DEFAULT_AUTH_PROVIDER
+
+
+def normalize_trusted_proxy(value: str | None) -> str | None:
+    if value is None:
+        return None
+    return value.strip() or None
+
+
+def check_default_tenant(value: str) -> str:
+    from simple_module_db import PLATFORM_TENANT_ID, is_valid_tenant_id
+
+    value = value.strip()
+    if value == PLATFORM_TENANT_ID:
+        raise ValueError(f"default_tenant {value!r} is reserved for platform-owned rows")
+    if value and not is_valid_tenant_id(value):
+        raise ValueError(f"default_tenant {value!r} is not a valid tenant id")
+    return value
+
+
+def check_cors_wildcard(settings: HostSettings) -> None:
+    if settings.cors_allow_credentials and CORS_WILDCARD in settings.cors_allow_origins:
+        raise PydanticCustomError(
+            "cors_wildcard_credentials",
+            "cors_allow_origins '*' cannot be combined with cors_allow_credentials",
+            {RELATED_FIELDS_CTX: ["cors_allow_origins", "cors_allow_credentials"]},
+        )
+
+
+def check_default_locale_supported(settings: HostSettings) -> None:
+    if settings.i18n_default_locale not in settings.i18n_supported_locales:
+        # Model-level, so the error has no field location: the context
+        # names both halves, letting lenient boot hydration drop whichever
+        # one came from the DB instead of refusing to boot (#497).
+        raise PydanticCustomError(
+            "default_locale_unsupported",
+            "i18n_default_locale '{default}' is not in i18n_supported_locales {supported}",
+            {
+                "default": settings.i18n_default_locale,
+                "supported": settings.i18n_supported_locales,
+                RELATED_FIELDS_CTX: ["i18n_default_locale", "i18n_supported_locales"],
+            },
+        )