simple-module-hosting 0.0.1__py3-none-any.whl

simple_module_hosting/manifest.py

@@ -0,0 +1,250 @@
+"""Frontend pages manifest + per-module JS dependency discovery.
+
+* :func:`write_module_pages_manifest` emits the three generated files Vite
+  and Tailwind read at build time:
+  - ``modules.manifest.json`` — name -> absolute pages dir
+  - ``modules.generated.ts`` — ``import.meta.glob`` per module
+  - ``modules.generated.css`` — ``@source`` per wheel-installed module
+* :func:`read_module_package_json` / :func:`collect_module_js_deps` locate
+  the per-module ``package.json`` shipped inside wheels (or alongside the
+  source for editable installs) and aggregate its ``dependencies`` block.
+  Used by the ``sm sync-js-deps`` CLI.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+import logging
+import os
+from collections.abc import Sequence
+from pathlib import Path
+
+from simple_module_core import ModuleBase, get_module_package_name
+
+logger = logging.getLogger(__name__)
+
+_GENERATED_TS_HEADER = """\
+// AUTO-GENERATED by simple_module_hosting.manifest — do not edit by hand.
+// Regenerate with: sm gen-pages
+//
+// Maps ModuleName -> record of page import paths. Paths below are
+// relative to this file (host/client_app/) so that pages shipped inside
+// pip-installed module wheels are picked up by Vite's import.meta.glob.
+"""
+
+_GENERATED_CSS_HEADER = """\
+/* AUTO-GENERATED by simple_module_hosting.manifest — do not edit by hand.
+ * Regenerate with: sm gen-pages
+ *
+ * @source entries for module pages shipped inside pip-installed wheels.
+ * In-repo modules are covered by the static @source glob in
+ * host/client_app/styles.css.
+ */
+"""
+
+
+def repo_root_from_client_app(client_app_dir: Path) -> Path:
+    """Repo root is two levels above ``host/client_app/``.
+
+    Both ``write_module_pages_manifest`` and the ``sync-js-deps`` CLI
+    derive the workspace root from the host's client_app directory.
+    Centralized here so the heuristic lives in exactly one place.
+    """
+    return client_app_dir.resolve().parent.parent
+
+
+def compute_module_pages(modules: Sequence[ModuleBase]) -> dict[str, Path]:
+    """Return a ``{ModuleName: absolute pages/ Path}`` map for modules that ship TSX pages.
+
+    A module is included only if ``<package>/pages/`` exists on disk.
+    """
+    result: dict[str, Path] = {}
+    for mod in modules:
+        pkg_name = get_module_package_name(mod)
+        try:
+            pkg_root = importlib.resources.files(pkg_name)
+        except ModuleNotFoundError:
+            logger.debug(
+                "Module '%s': package %s not importable — skipping", mod.meta.name, pkg_name
+            )
+            continue
+        pages_dir = Path(str(pkg_root)) / "pages"
+        if not pages_dir.is_dir():
+            logger.debug(
+                "Module '%s' has no pages/ at %s — skipping frontend manifest entry",
+                mod.meta.name,
+                pages_dir,
+            )
+            continue
+        result[mod.meta.name] = pages_dir.resolve()
+    return result
+
+
+def _write_if_changed(path: Path, payload: str) -> bool:
+    """Write ``payload`` to ``path`` only if the on-disk content differs.
+
+    Avoids bumping the file's mtime on every dev-server boot, which would
+    otherwise cascade into Vite's file-watcher and trigger spurious HMR.
+    Returns True if a write happened.
+    """
+    try:
+        existing = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        existing = None
+    if existing == payload:
+        return False
+    path.write_text(payload, encoding="utf-8")
+    return True
+
+
+def _is_in_repo_module(pages_dir: Path, repo_root: Path | None) -> bool:
+    """True if ``pages_dir`` lives under the working tree's ``modules/`` dir.
+
+    Those modules are already covered by the static ``@source`` glob in
+    host/client_app/styles.css, so we shouldn't emit a duplicate absolute
+    entry for them in the generated CSS.
+    """
+    if repo_root is None:
+        return False
+    try:
+        rel = pages_dir.resolve().relative_to(repo_root.resolve())
+    except ValueError:
+        return False
+    return len(rel.parts) >= 2 and rel.parts[0] == "modules"
+
+
+def write_module_pages_manifest(
+    modules: Sequence[ModuleBase],
+    output_dir: Path,
+    repo_root: Path | None = None,
+) -> dict[str, Path]:
+    """Write the three generated files (manifest JSON, glob TS, Tailwind CSS).
+
+    Returns the paths that were written. Content is written only when
+    different from what's on disk, so booting the host repeatedly in dev
+    does not wake up Vite's file watcher.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    if repo_root is None:
+        repo_root = repo_root_from_client_app(output_dir)
+
+    pages_map = compute_module_pages(modules)
+
+    manifest_path = output_dir / "modules.manifest.json"
+    manifest_payload = {name: path.as_posix() for name, path in pages_map.items()}
+    manifest_text = json.dumps(manifest_payload, indent=2, sort_keys=True) + "\n"
+
+    generated_path = output_dir / "modules.generated.ts"
+    lines: list[str] = [
+        _GENERATED_TS_HEADER,
+        "",
+        "import type { ComponentType } from 'react';",
+        "",
+        "type PageModule = { default: ComponentType<Record<string, unknown>> };",
+        "",
+        "export const moduleGlobs: Record<string, Record<string, () => Promise<PageModule>>> = {",
+    ]
+    for name in sorted(pages_map):
+        lines.append(
+            f"  {json.dumps(name)}: import.meta.glob<PageModule>"
+            f"({json.dumps(_glob_pattern_for(pages_map[name], output_dir))}),"
+        )
+    lines.append("};")
+    lines.append("")
+    generated_text = "\n".join(lines)
+
+    # In-repo modules are already covered by the static glob in styles.css;
+    # only emit @source for wheel-installed ones. pages_map is keyed by
+    # module name so each pages_dir is unique — no further dedup needed.
+    css_path = output_dir / "modules.generated.css"
+    css_lines: list[str] = [_GENERATED_CSS_HEADER]
+    for name in sorted(pages_map):
+        pages_dir = pages_map[name]
+        if _is_in_repo_module(pages_dir, repo_root):
+            continue
+        css_lines.append(f'@source "{pages_dir.as_posix()}";')
+    css_lines.append("")
+    css_text = "\n".join(css_lines)
+
+    wrote_manifest = _write_if_changed(manifest_path, manifest_text)
+    wrote_generated = _write_if_changed(generated_path, generated_text)
+    wrote_css = _write_if_changed(css_path, css_text)
+
+    if wrote_manifest or wrote_generated or wrote_css:
+        logger.info(
+            "Wrote module pages manifest: %d module(s) -> %s, %s, %s",
+            len(pages_map),
+            manifest_path.name,
+            generated_path.name,
+            css_path.name,
+        )
+    return {"manifest": manifest_path, "generated": generated_path, "css": css_path}
+
+
+def _glob_pattern_for(pages_dir: Path, output_dir: Path) -> str:
+    """Build a Vite ``import.meta.glob`` pattern relative to ``output_dir``.
+
+    Vite 8 interprets filesystem-absolute paths against the project root,
+    not the filesystem, so we always emit the path relative to the file
+    where the glob lives (``modules.generated.ts`` under ``output_dir``).
+    """
+    try:
+        rel = Path(os.path.relpath(pages_dir, output_dir.resolve()))
+    except ValueError:
+        # Different drive on Windows — fall back to absolute (rare).
+        return pages_dir.as_posix() + "/**/*.tsx"
+    rel_str = rel.as_posix()
+    if not rel_str.startswith(("./", "../")):
+        rel_str = "./" + rel_str
+    return rel_str + "/**/*.tsx"
+
+
+def read_module_package_json(mod: ModuleBase) -> dict | None:
+    """Return the parsed ``package.json`` for a module, or ``None`` if absent.
+
+    Tries two locations so both install modes work:
+
+    * ``<pkg>/package.json`` — force-included into the wheel by Hatch.
+    * ``<pkg>/../package.json`` — the source-tree module root, used by
+      editable installs and in-repo workspace members where the wheel
+      hasn't been built yet.
+    """
+    pkg_name = get_module_package_name(mod)
+    try:
+        pkg_root = Path(str(importlib.resources.files(pkg_name)))
+    except ModuleNotFoundError:
+        return None
+    for candidate in (pkg_root / "package.json", pkg_root.parent / "package.json"):
+        if candidate.is_file():
+            try:
+                return json.loads(candidate.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                logger.warning(
+                    "Module '%s' has an invalid package.json at %s: %s",
+                    mod.meta.name,
+                    candidate,
+                    exc,
+                )
+                return None
+    return None
+
+
+def collect_module_js_deps(modules: Sequence[ModuleBase]) -> dict[str, dict[str, str]]:
+    """Return ``{module_name: {dep: range}}`` for modules that declare deps.
+
+    Reads only the ``dependencies`` block; ``peerDependencies`` are
+    host-provided singletons and must not be installed from modules.
+    Modules without a ``package.json`` or without a ``dependencies`` block
+    are silently skipped.
+    """
+    out: dict[str, dict[str, str]] = {}
+    for mod in modules:
+        pkg = read_module_package_json(mod)
+        if not pkg:
+            continue
+        deps = pkg.get("dependencies") or {}
+        if deps:
+            out[mod.meta.name] = {str(k): str(v) for k, v in deps.items()}
+    return out

simple_module_hosting/middleware.py

@@ -0,0 +1,272 @@
+"""Middleware: security headers, tenant isolation, Inertia shared-props.
+
+Correlation IDs and request logging live in :mod:`._observability`.
+
+All middleware classes use the raw ASGI pattern instead of ``BaseHTTPMiddleware``
+to avoid its known issues with streaming responses, extra task creation,
+and ``ContextVar`` propagation.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from simple_module_db import current_tenant_id
+from starlette.datastructures import Headers, MutableHeaders
+from starlette.requests import Request
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from simple_module_hosting._inertia_shared import build_i18n_block
+from simple_module_hosting._observability import (
+    CorrelationIdMiddleware,
+    RequestLoggingMiddleware,
+)
+from simple_module_hosting.permissions import expand_permissions, resolve_permissions
+
+if TYPE_CHECKING:
+    from simple_module_core.menu import MenuRegistry
+    from simple_module_core.permissions import PermissionRegistry
+
+logger = logging.getLogger(__name__)
+
+_SCOPE_HTTP = "http"
+_MSG_RESPONSE_START = "http.response.start"
+
+# Security response header names
+_HEADER_X_CONTENT_TYPE_OPTIONS = "X-Content-Type-Options"
+_HEADER_X_FRAME_OPTIONS = "X-Frame-Options"
+_HEADER_X_XSS_PROTECTION = "X-XSS-Protection"
+_HEADER_REFERRER_POLICY = "Referrer-Policy"
+_HEADER_CSP = "Content-Security-Policy"
+_HEADER_HSTS = "Strict-Transport-Security"
+
+# Security response header values
+_XCTO_NOSNIFF = "nosniff"
+_XFO_SAMEORIGIN = "SAMEORIGIN"
+_XXSS_BLOCK = "1; mode=block"
+_REFERRER_STRICT_ORIGIN = "strict-origin-when-cross-origin"
+
+__all__ = [
+    "TENANT_HEADER",
+    "CorrelationIdMiddleware",
+    "InertiaLayoutDataMiddleware",
+    "RequestLoggingMiddleware",
+    "SecurityHeadersMiddleware",
+    "TenantMiddleware",
+]
+
+
+class SecurityHeadersMiddleware:
+    """Add security headers to every response.
+
+    ``content_security_policy`` and ``strict_transport_security`` accept a
+    string to override the defaults, or ``None`` to suppress that header
+    (useful in development when Vite's HMR client loads cross-origin scripts,
+    or behind plain-HTTP loopbacks where HSTS would lock users out).
+    """
+
+    _DEFAULT_CSP = (
+        "default-src 'self'; "
+        # Inertia embeds the initial page blob inline; Vite injects a React
+        # Refresh shim at boot. Both require 'unsafe-inline' for scripts.
+        # Production builds compile to hashed bundles, so this can be
+        # tightened with a nonce once Vite's preamble is removed in prod.
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval'; "
+        "script-src-elem 'self' 'unsafe-inline'; "
+        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "
+        "img-src 'self' data: blob:; "
+        "font-src 'self' https://fonts.gstatic.com data:; "
+        "connect-src 'self'; "
+        "frame-ancestors 'self'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    )
+    _DEFAULT_HSTS = "max-age=31536000; includeSubDomains"
+
+    @staticmethod
+    def dev_csp(vite_dev_url: str) -> str:
+        """Build a dev CSP that whitelists the Vite dev server.
+
+        In development the browser fetches ``@vite/client``, ``main.tsx``, and
+        React Refresh from the Vite origin (default ``http://localhost:5050``),
+        and opens a WebSocket there for HMR. Those fail under the prod CSP,
+        so we widen ``script-src*``/``connect-src``/``style-src`` for that
+        origin only (including the ``ws://`` equivalent for HMR).
+        """
+        ws_url = vite_dev_url.replace("http://", "ws://").replace("https://", "wss://")
+        return (
+            "default-src 'self'; "
+            f"script-src 'self' 'unsafe-inline' 'unsafe-eval' {vite_dev_url}; "
+            f"script-src-elem 'self' 'unsafe-inline' {vite_dev_url}; "
+            f"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com {vite_dev_url}; "
+            "img-src 'self' data: blob:; "
+            "font-src 'self' https://fonts.gstatic.com data:; "
+            f"connect-src 'self' {vite_dev_url} {ws_url}; "
+            "frame-ancestors 'self'; "
+            "base-uri 'self'; "
+            "form-action 'self'"
+        )
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        content_security_policy: str | None = _DEFAULT_CSP,
+        strict_transport_security: str | None = _DEFAULT_HSTS,
+    ) -> None:
+        self.app = app
+        self.csp = content_security_policy
+        self.hsts = strict_transport_security
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        async def send_with_headers(message: Message) -> None:
+            if message["type"] == _MSG_RESPONSE_START:
+                headers = MutableHeaders(scope=message)
+                headers[_HEADER_X_CONTENT_TYPE_OPTIONS] = _XCTO_NOSNIFF
+                headers[_HEADER_X_FRAME_OPTIONS] = _XFO_SAMEORIGIN
+                headers[_HEADER_X_XSS_PROTECTION] = _XXSS_BLOCK
+                headers[_HEADER_REFERRER_POLICY] = _REFERRER_STRICT_ORIGIN
+                if self.csp:
+                    headers[_HEADER_CSP] = self.csp
+                if self.hsts:
+                    headers[_HEADER_HSTS] = self.hsts
+            await send(message)
+
+        await self.app(scope, receive, send_with_headers)
+
+
+TENANT_HEADER = "X-Tenant-ID"
+
+
+class TenantMiddleware:
+    """Extract tenant context from authenticated user or request header.
+
+    Sets the ``current_tenant_id`` context var so that DB queries on
+    :class:`~simple_module_db.mixins.MultiTenantMixin` models are
+    automatically filtered, and new objects get ``tenant_id`` populated.
+
+    Also stores the resolved value on ``request.state.tenant_id``.
+
+    Tenant is resolved from (in priority order):
+
+    1. Authenticated user's ``tenant_id`` attribute (from auth token claims).
+    2. The configured request header, if any — useful for API clients
+       and tests. Pass ``header=None`` (the default) to disable the
+       header source and force tenant resolution through the auth token
+       only. Pass the header name (e.g. ``"X-Tenant-ID"``) to enable.
+    """
+
+    def __init__(self, app: ASGIApp, *, header: str | None = None) -> None:
+        self.app = app
+        self.header = header
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        tenant_id: str | None = None
+
+        user = getattr(request.state, "user", None)
+        if user is not None:
+            tenant_id = getattr(user, "tenant_id", None)
+
+        if tenant_id is None and self.header:
+            header_value = Headers(scope=scope).get(self.header)
+            if header_value:
+                tenant_id = header_value
+
+        request.state.tenant_id = tenant_id
+
+        if tenant_id is not None:
+            token = current_tenant_id.set(tenant_id)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                current_tenant_id.reset(token)
+            return
+
+        await self.app(scope, receive, send)
+
+
+PrincipalSerializer = Callable[[Any], dict[str, Any]]
+"""Module-owned projection from ``request.state.user`` to the ``auth.user``
+shared-prop dict. Framework never inspects user fields beyond ``roles``; a
+module (typically ``users``) registers a serializer on ``app.state`` so the
+user-schema stays out of the hosting layer."""
+
+
+class InertiaLayoutDataMiddleware:
+    """Inject shared data (auth, menus, i18n) into every Inertia response.
+
+    This middleware reads the user from ``request.state.user`` (set by auth middleware)
+    and populates ``request.state.inertia_shared`` for the Inertia render function.
+
+    The ``auth.user`` projection is produced by a module-registered serializer
+    looked up on ``request.app.state.principal_serializer``. Without one,
+    ``auth.user`` is ``None`` even when a user is authenticated.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        menu_registry: MenuRegistry,
+        permission_registry: PermissionRegistry,
+    ) -> None:
+        self.app = app
+        self.menu_registry = menu_registry
+        self.permission_registry = permission_registry
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != _SCOPE_HTTP:
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        user = getattr(request.state, "user", None)
+        is_authenticated = user is not None
+        roles = getattr(user, "roles", []) if user else []
+
+        # Resolve permissions once and cache on request.state for RequiresPermission
+        resolved = (
+            resolve_permissions(roles, role_map=self.permission_registry.role_map)
+            if is_authenticated
+            else set()
+        )
+        request.state.resolved_permissions = resolved
+
+        # Expand wildcard to full list for frontend (no "*" leak)
+        all_perms = self.permission_registry.all_permissions
+        frontend_permissions = expand_permissions(resolved, all_perms) if is_authenticated else []
+
+        i18n_block = build_i18n_block(scope, request)
+
+        principal_serializer: PrincipalSerializer | None = getattr(
+            scope["app"].state, "principal_serializer", None
+        )
+        user_payload: dict[str, Any] | None = (
+            principal_serializer(user) if user is not None and principal_serializer else None
+        )
+
+        shared: dict = {
+            "auth": {
+                "user": user_payload,
+                "isAuthenticated": is_authenticated,
+                "permissions": frontend_permissions,
+            },
+            "menus": self.menu_registry.get_for_user(
+                is_authenticated=is_authenticated,
+                roles=roles,
+            ),
+            "i18n": i18n_block,
+        }
+        request.state.inertia_shared = shared
+
+        await self.app(scope, receive, send)

simple_module_hosting/migrations.py

@@ -0,0 +1,65 @@
+"""Alembic migration check performed during app startup."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_head_revision(alembic_ini_path: str = "host/alembic.ini") -> str | None:
+    """Return the current head revision string, or ``None`` if alembic
+    isn't configured at ``alembic_ini_path`` or has no revisions."""
+    from alembic.config import Config as AlembicConfig
+    from alembic.script import ScriptDirectory
+    from alembic.util.exc import CommandError
+
+    try:
+        return ScriptDirectory.from_config(AlembicConfig(alembic_ini_path)).get_current_head()
+    except (CommandError, FileNotFoundError) as exc:
+        logger.debug("Alembic not available: %s", exc)
+        return None
+
+
+async def check_migrations(engine, alembic_ini_path: str = "host/alembic.ini") -> dict:
+    """Check database migration state. Raises RuntimeError if not at head.
+
+    Returns a dict with migration status for storage on app.state.
+    """
+    from alembic.config import Config as AlembicConfig
+    from alembic.runtime.migration import MigrationContext
+    from alembic.script import ScriptDirectory
+
+    _no_migrations = {
+        "current_revision": None,
+        "head_revision": None,
+        "is_current": True,
+        "pending_count": 0,
+    }
+
+    head = resolve_head_revision(alembic_ini_path)
+    if head is None:
+        return _no_migrations
+    script = ScriptDirectory.from_config(AlembicConfig(alembic_ini_path))
+
+    async with engine.connect() as conn:
+
+        def _get_current(sync_conn):
+            ctx = MigrationContext.configure(sync_conn)
+            return ctx.get_current_revision()
+
+        current = await conn.run_sync(_get_current)
+
+    if current != head:
+        pending = list(script.iterate_revisions(head, current))
+        raise RuntimeError(
+            f"Database is {len(pending)} revision(s) behind "
+            f"(at {current!r}, head is {head!r}). Run: make migrate"
+        )
+
+    return {
+        "current_revision": current,
+        "head_revision": head,
+        "is_current": True,
+        "pending_count": 0,
+    }

simple_module_hosting/permissions.py

@@ -0,0 +1,75 @@
+"""Permission enforcement dependency for FastAPI endpoints."""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, Request
+from simple_module_core.permissions import DEFAULT_ROLE_PERMISSIONS, WILDCARD
+
+__all__ = [
+    "DEFAULT_ROLE_PERMISSIONS",
+    "WILDCARD",
+    "RequiresPermission",
+    "expand_permissions",
+    "resolve_permissions",
+]
+
+
+def resolve_permissions(
+    roles: list[str],
+    role_map: dict[str, list[str]] | None = None,
+) -> set[str]:
+    """Resolve a set of roles into a flat set of permission strings."""
+    if role_map is None:
+        role_map = DEFAULT_ROLE_PERMISSIONS
+    permissions: set[str] = set()
+    for role in roles:
+        permissions.update(role_map.get(role, []))
+    return permissions
+
+
+def expand_permissions(
+    resolved: set[str],
+    all_permissions: list[str],
+) -> list[str]:
+    """Expand wildcard to the full permission list for frontend consumption."""
+    if WILDCARD in resolved:
+        return sorted(set(all_permissions))
+    return sorted(resolved)
+
+
+class RequiresPermission:
+    """FastAPI dependency that enforces a specific permission.
+
+    Usage::
+
+        @router.post("/", dependencies=[Depends(RequiresPermission("products.create"))])
+        async def create_product(...):
+            ...
+    """
+
+    def __init__(self, permission: str) -> None:
+        self.permission = permission
+
+    def __call__(self, request: Request) -> None:
+        user = getattr(request.state, "user", None)
+        if user is None:
+            raise HTTPException(status_code=401, detail="Authentication required")
+
+        # Use cached permissions from middleware if available
+        permissions: set[str] | None = getattr(request.state, "resolved_permissions", None)
+        if permissions is None:
+            # Fallback: middleware did not run — consult registry role_map if available
+            sm = getattr(getattr(request.app, "state", None), "sm", None)
+            perm_registry = getattr(sm, "permissions", None) if sm is not None else None
+            role_map = perm_registry.role_map if perm_registry is not None else None
+            permissions = resolve_permissions(user.roles, role_map=role_map)
+            request.state.resolved_permissions = permissions
+
+        if WILDCARD in permissions:
+            return
+
+        if self.permission not in permissions:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Permission required: {self.permission}",
+            )