simple-module-core 0.0.30__tar.gz → 0.0.31__tar.gz

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/.gitignore

@@ -63,3 +63,4 @@ Thumbs.db
 host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
+.verify/

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.30
+Version: 0.0.31
 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.30 → simple_module_core-0.0.31}/pyproject.toml

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

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/__init__.py

@@ -1,5 +1,7 @@
 """SimpleModule Core - Module system, menu, permissions, events, and diagnostics."""
 
+from simple_module_core.audit_links import AuditLink, AuditLinkRegistry
+from simple_module_core.csp import CspSourceError, CspSourceRegistry
 from simple_module_core.design_packs import DesignPack, DesignPackRegistry
 from simple_module_core.diagnostics import (
     DiagnosticLevel,
@@ -44,7 +46,11 @@ from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework
 __all__ = [
     "DEFAULT_AUTH_PROVIDER",
     "FRAMEWORK_API_VERSION",
+    "AuditLink",
+    "AuditLinkRegistry",
     "CircularDependencyError",
+    "CspSourceError",
+    "CspSourceRegistry",
     "DesignPack",
     "DesignPackRegistry",
     "DiagnosticLevel",

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/__main__.py

@@ -9,7 +9,8 @@ Exits with status 1 if any ERROR-level diagnostics are reported.
 
 i18n checks are included when ``SM_I18N_SUPPORTED_LOCALES`` is set in env
 (or ``.env``). Host-level ``host/locales/`` and shared ``packages/ui/locales/``
-are picked up relative to ``SM_PROJECT_ROOT`` (or the current working dir).
+are picked up relative to the project root (``SM_PROJECT_ROOT``, else the
+directory of the discovered ``.env``, else the current working dir).
 """
 
 from __future__ import annotations
@@ -31,7 +32,7 @@ from simple_module_core.discovery import (
     select_auth_provider,
     topological_sort,
 )
-from simple_module_core.dotenv import parse_dotenv
+from simple_module_core.dotenv import find_env_file, parse_dotenv
 from simple_module_core.exceptions import InvalidModuleError
 
 
@@ -64,7 +65,11 @@ def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
 
 def _discover_extra_locale_sources() -> list[tuple[str, str, Path]]:
     """Return ``[(reporter, namespace, path), ...]`` for host + ui locale dirs."""
-    root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
+    # Anchor on the same project root the `.env` was loaded from
+    # (`parse_dotenv` walks up from the cwd) — resolving against the bare cwd
+    # here would look for `host/locales` in the wrong directory whenever
+    # doctor runs from a subdirectory.
+    root = find_env_file().parent
     out: list[tuple[str, str, Path]] = []
     host_locales = root / "host" / "locales"
     if host_locales.is_dir():

simple_module_core-0.0.31/simple_module_core/audit_links.py

@@ -0,0 +1,84 @@
+"""Audit-link registry — modules teach the audit log how to reach their records.
+
+An audit entry stores the *model class name* and primary key of the row that
+changed (``StoredFile``, ``a91f3c2b…`` — ``snapshot_changes`` records
+``type(obj).__name__``, never ``__tablename__``). That is enough to prove what
+happened and useless for doing anything about it: the reader has an id and no
+way to open the record it names.
+
+A module declares where its rows live via
+:meth:`~simple_module_core.module.ModuleBase.register_audit_links`; the host
+collects them into one registry at boot and stores it on
+``app.state.sm.audit_links``.
+
+**The registry maps model class names to URL templates, nothing more.** It does
+not verify the row exists or that the reader may open it — following a link to a
+deleted record lands on that screen's own 404, and permissions are enforced by
+the target route as usual.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_ID_PLACEHOLDER = "{id}"
+
+
+@dataclass(frozen=True)
+class AuditLink:
+    """Where the records of one audited model can be viewed.
+
+    Args:
+        entity_type: The **model class name**, matching
+            ``AuditEntry.entity_type`` (e.g. ``"User"``, not ``"users_user"``).
+            ``snapshot_changes`` records ``type(obj).__name__``, so keying this
+            off ``__tablename__`` silently never matches — and because an
+            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"``).
+        label: Human-readable name for the entity kind, shown instead of the
+            raw class name (e.g. ``"User account"``).
+    """
+
+    entity_type: str
+    url_template: str
+    label: str = ""
+
+    def __post_init__(self) -> None:
+        if _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:
+        return self.url_template.replace(_ID_PLACEHOLDER, entity_id)
+
+
+class AuditLinkRegistry:
+    """Aggregates every module's :class:`AuditLink` declarations.
+
+    Populated once during boot (``register_audit_links`` hook) and read
+    thereafter by the audit log view when it renders each row.
+    """
+
+    def __init__(self) -> None:
+        self._links: dict[str, AuditLink] = {}
+
+    def register(self, link: AuditLink) -> None:
+        existing = self._links.get(link.entity_type)
+        if existing is not None and existing != link:
+            raise ValueError(
+                f"Two modules claim audit links for {link.entity_type!r}: "
+                f"{existing.url_template!r} and {link.url_template!r}"
+            )
+        self._links[link.entity_type] = link
+
+    def get(self, entity_type: str) -> AuditLink | None:
+        return self._links.get(entity_type)
+
+    @property
+    def all_links(self) -> dict[str, AuditLink]:
+        return dict(self._links)

simple_module_core-0.0.31/simple_module_core/csp.py

@@ -0,0 +1,140 @@
+"""Registry for module-contributed Content-Security-Policy sources.
+
+Modules whose frontend loads assets from an external origin (a font CDN, a
+tile server, an analytics endpoint) declare those origins through
+``ModuleBase.register_csp_sources``. The host folds them into the CSP it
+already ships — the module never rewrites the whole policy, and a typo'd
+origin fails loudly at boot instead of silently weakening the header.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["CspSourceError", "CspSourceRegistry"]
+
+# Fetch directives a module may extend. Deliberately excludes the policy's
+# structural directives (default-src, base-uri, form-action, frame-ancestors,
+# sandbox): widening those changes the security posture of the whole app and
+# belongs to the host operator, not a module.
+_EXTENDABLE_DIRECTIVES = frozenset(
+    {
+        "script-src",
+        "script-src-elem",
+        "style-src",
+        "style-src-elem",
+        "img-src",
+        "font-src",
+        "connect-src",
+        "media-src",
+        "frame-src",
+        "worker-src",
+        "child-src",
+    }
+)
+
+# A source is a scheme, an origin (optionally with scheme/wildcard/port), or
+# a data-ish scheme keyword. One token — anything that could smuggle a second
+# token or terminate/extend the clause (whitespace, ";", ",", quotes) is
+# rejected, and a wildcard prefix must be followed by a real host (`*.` alone
+# is not a source).
+_SOURCE_RE = re.compile(r"^(?:[A-Za-z][A-Za-z0-9+.-]*:(?://)?)?(?:(?:\*\.)?[^\s;,'\"*]+)?$")
+
+# CSP3 fallback chains: when a directive is absent from a policy, the browser
+# consults these directives in order (ending at ``default-src``). A clause we
+# append for a previously-absent directive must be seeded from the nearest
+# clause the policy already has along this chain — seeding with a bare
+# ``'self'`` would *narrow* the policy (e.g. a fresh ``style-src-elem`` clause
+# cuts off the fallback to ``style-src`` and silently drops its
+# ``'unsafe-inline'`` and font origins).
+_FALLBACK_CHAINS: dict[str, tuple[str, ...]] = {
+    "script-src-elem": ("script-src", "default-src"),
+    "style-src-elem": ("style-src", "default-src"),
+    "frame-src": ("child-src", "default-src"),
+    "worker-src": ("child-src", "script-src", "default-src"),
+}
+
+
+class CspSourceError(ValueError):
+    """Invalid CSP directive or source declared by a module."""
+
+
+class CspSourceRegistry:
+    """Collects per-directive extra CSP sources from modules."""
+
+    def __init__(self) -> None:
+        self._sources: dict[str, list[str]] = {}
+
+    def add(self, directive: str, source: str) -> None:
+        """Allow ``source`` in ``directive``, e.g. ``add("style-src", "https://rsms.me")``."""
+        if directive not in _EXTENDABLE_DIRECTIVES:
+            raise CspSourceError(
+                f"CSP directive {directive!r} is not extendable; "
+                f"choose one of {sorted(_EXTENDABLE_DIRECTIVES)}"
+            )
+        token = source.strip()
+        if not token or not _SOURCE_RE.match(token):
+            raise CspSourceError(
+                f"invalid CSP source {source!r} for {directive}: must be a single "
+                "origin or scheme token (no spaces, quotes, wildcards-only, or ';')"
+            )
+        bucket = self._sources.setdefault(directive, [])
+        if token not in bucket:
+            bucket.append(token)
+
+    def __bool__(self) -> bool:
+        return bool(self._sources)
+
+    def extend_policy(self, policy: str) -> str:
+        """Fold the registered sources into an existing policy string.
+
+        Existing clauses keep their order and gain only sources they don't
+        already list. A directive absent from the policy is appended as a new
+        clause seeded from the clause the browser would otherwise have fallen
+        back to (per ``_FALLBACK_CHAINS``, ending at ``default-src``) —
+        without that seed the new clause would *narrow* the policy, since the
+        browser stops consulting the fallback once the directive exists.
+        """
+        if not self._sources:
+            return policy
+        directives: dict[str, list[str]] = {}
+        order: list[str] = []
+        for clause in policy.split(";"):
+            clause = clause.strip()
+            if not clause:
+                continue
+            directive, _, rest = clause.partition(" ")
+            directives[directive] = rest.split()
+            order.append(directive)
+        for directive, extras in self._sources.items():
+            if directive not in directives:
+                directives[directive] = list(self._seed_sources(directive, directives))
+                order.append(directive)
+            bucket = directives[directive]
+            bucket.extend(e for e in extras if e not in bucket)
+        # A more-specific directive *shadows* its fallback chain once present:
+        # with `script-src-elem` already in the policy, a module's
+        # `script-src` addition would never reach <script> elements — the
+        # very load the module declared it for. The same shadowing applies to
+        # every pair `_FALLBACK_CHAINS` encodes (an existing `frame-src` or
+        # `worker-src` clause shadows a module's `child-src` extras, and
+        # `worker-src` shadows `script-src` too). Mirror base-directive
+        # extras into each present shadowing clause so the declaration keeps
+        # exactly the meaning the fallback would have given it.
+        for shadowing, chain in _FALLBACK_CHAINS.items():
+            if shadowing not in directives:
+                continue
+            bucket = directives[shadowing]
+            for base in chain:
+                extras = self._sources.get(base)
+                if extras:
+                    bucket.extend(e for e in extras if e not in bucket)
+        return "; ".join(f"{d} {' '.join(directives[d])}".rstrip() for d in order)
+
+    @staticmethod
+    def _seed_sources(directive: str, directives: dict[str, list[str]]) -> list[str]:
+        """Sources a brand-new clause inherits from its CSP fallback chain."""
+        for fallback in (*_FALLBACK_CHAINS.get(directive, ()), "default-src"):
+            if fallback in directives:
+                return directives[fallback]
+        return ["'self'"]

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/diagnostics/_module.py

@@ -98,6 +98,7 @@ class ModuleDiagnostics:
                     "register_middleware",
                     "register_health_checks",
                     "register_public_routes",
+                    "register_csp_sources",
                     "register_exception_handlers",
                     "register_settings",
                     "template_dirs",

simple_module_core-0.0.31/simple_module_core/dotenv.py

@@ -0,0 +1,141 @@
+"""Minimal ``.env`` parser + env-var helpers — dependency-free.
+
+Used in places that can't or shouldn't pull in ``pydantic-settings`` (the
+diagnostics CLI runs before the host package is imported; the users-module
+bootstrap runs after settings are constructed and needs to read values that
+``UsersSettings`` deliberately omits from ``env_file``).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+BOOL_LITERALS_TRUE = frozenset({"1", "true", "t", "yes", "y", "on"})
+BOOL_LITERALS_FALSE = frozenset({"0", "false", "f", "no", "n", "off"})
+
+# How many parent directories to probe for a `.env` above the cwd. One level
+# covers the workspace layout (`host/` → root); a couple more cover running
+# from `modules/<name>/`. Bounded so an unrelated `.env` far up the tree
+# (e.g. in $HOME) is never picked up by accident.
+_ENV_WALK_LIMIT = 4
+
+
+def find_env_file() -> Path:
+    """Locate the project ``.env`` regardless of which subdirectory runs us.
+
+    ``$SM_PROJECT_ROOT/.env`` wins when set. Otherwise walk up from the cwd:
+    the web process chdirs to the workspace root so this finds ``./.env``
+    immediately, while a CLI invoked from ``host/`` or ``modules/<name>/``
+    finds the same file its app uses instead of silently loading nothing.
+    When the walk hits a project-root marker (``.git`` / ``.env.example``)
+    without finding a ``.env``, the returned path is ``<root>/.env`` — it may
+    not exist, but its *parent* still anchors relative sqlite paths at the
+    project root (a fresh scaffold has ``.env.example`` before any ``.env``).
+    Falls back to a cwd-relative ``Path(".env")`` when nothing is found.
+
+    This is the one .env-resolution convention for the whole ecosystem: the
+    settings layer (``BootstrapSettings``) and every out-of-process tool
+    (diagnostics CLI, worker entrypoints, users bootstrap) resolve through
+    here, so they can never disagree about which file is in effect. Compare
+    ``app_builder._resolve_project_root`` in the hosting package — a
+    separate walk that anchors the static/i18n root instead; the two are
+    kept distinct on purpose (see that function's docstring).
+    """
+    explicit = os.environ.get("SM_PROJECT_ROOT")
+    if explicit:
+        return Path(explicit) / ".env"
+    current = Path.cwd()
+    try:
+        home: Path | None = Path.home()
+    except RuntimeError:
+        # $HOME unset and no passwd entry for the UID (rootless containers,
+        # some CI sandboxes) — Path.home() can't resolve. Skip the
+        # home-boundary check rather than crash; the walk is still bounded
+        # by _ENV_WALK_LIMIT and the world-writable-dir guard below.
+        home = None
+    for candidate in (current, *current.parents[:_ENV_WALK_LIMIT]):
+        if home is not None and candidate == home:
+            break
+        # Never probe a shared world-writable ancestor (/tmp, /var/tmp):
+        # its `.env` could belong to anyone — including another local user —
+        # and callers merge every key of the discovered file into os.environ.
+        # The starting cwd itself is exempt: running *from* such a directory
+        # keeps the pre-existing "load the cwd's .env" behavior via the fallback.
+        if candidate != current and _is_world_writable_dir(candidate):
+            break
+        env = candidate / ".env"
+        if env.is_file():
+            return env
+        # A `.git` or `.env.example` marks a project root: never ascend past
+        # one, or a nested checkout (a git worktree, a repo inside another
+        # repo, a fresh scaffold — which ships `.env.example` before any
+        # `.git` exists) would silently load the *outer* project's `.env`.
+        # The boundary directory IS the project root, so anchor there: a
+        # fresh scaffold with only `.env.example` must still resolve
+        # relative sqlite paths against its root, not the caller's cwd.
+        if (candidate / ".git").exists() or (candidate / ".env.example").is_file():
+            return candidate / ".env"
+    return Path(".env")
+
+
+def _is_world_writable_dir(path: Path) -> bool:
+    """True for shared scratch dirs like ``/tmp`` (world-writable, sticky or not)."""
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return False
+    return bool(mode & 0o002)
+
+
+def parse_dotenv(path: Path | None = None) -> dict[str, str]:
+    """Parse a ``.env`` file into a dict. Empty dict if the file is missing.
+
+    Values surrounded by matching single or double quotes have the quotes
+    stripped. Does *not* handle escapes, ``export KEY=…``, or multiline
+    values — keep the file simple. Does *not* mutate ``os.environ``; the
+    caller decides whether to merge.
+
+    Without ``path``, resolves via :func:`find_env_file` — the convention
+    used by every tool in this repo.
+    """
+    if path is None:
+        path = find_env_file()
+    if not path.is_file():
+        return {}
+    parsed: dict[str, str] = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        parsed[key.strip()] = value.strip().strip('"').strip("'")
+    return parsed
+
+
+def load_dotenv_into_environ(path: Path | None = None) -> None:
+    """Merge ``parse_dotenv(path)`` into ``os.environ`` via ``setdefault``.
+
+    Same precedence as the web process under uvicorn: real environment wins
+    over file values. Worker entrypoints call this before importing settings.
+    """
+    for key, value in parse_dotenv(path).items():
+        os.environ.setdefault(key, value)
+
+
+def env_str(name: str, default: str) -> str:
+    """Return ``$name`` if set and non-empty, else ``default``."""
+    value = os.environ.get(name, "").strip()
+    return value or default
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    """Parse ``$name`` as a boolean, returning ``default`` when unset/blank."""
+    raw = os.environ.get(name, "").strip().lower()
+    if not raw:
+        return default
+    if raw in BOOL_LITERALS_TRUE:
+        return True
+    if raw in BOOL_LITERALS_FALSE:
+        return False
+    return default

simple_module_core-0.0.31/simple_module_core/health.py

@@ -0,0 +1,84 @@
+"""Health check registry for module-contributed health checks."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class HealthStatus(StrEnum):
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a single health check."""
+
+    status: HealthStatus
+    detail: str | None = None
+
+
+HealthCheckFn = Callable[[], Awaitable[HealthCheckResult]]
+
+
+@dataclass
+class HealthCheck:
+    """A named health check with an async callable."""
+
+    name: str
+    check: HealthCheckFn
+    module: str = ""
+    """Module that contributed the check. Stamped by the registry during
+    ``register_health_checks``; module authors never set it by hand."""
+    probe: bool = True
+    """Whether automatic pollers may run this check.
+
+    Set ``False`` for checks that reach a third party — an SMTP login, an S3
+    request. Readiness is asked on a timer (a Kubernetes probe every 10s), and
+    a check that authenticates against a mail provider on that schedule earns
+    a rate-limit and binds probe latency to someone else's uptime. Such a
+    dependency is also not a readiness signal: the app serves pages fine while
+    its mailer is down.
+
+    ``False`` checks still run when explicitly requested — that is what the
+    "Test connection" action on the module-settings screen invokes.
+    """
+
+
+class HealthRegistry:
+    """Collects health checks contributed by modules."""
+
+    def __init__(self) -> None:
+        self._checks: list[HealthCheck] = []
+        self._current_owner: str = ""
+
+    def set_owner(self, module_name: str) -> None:
+        """Attribute subsequently-added checks to ``module_name``.
+
+        The host calls this around each ``register_health_checks`` hook so a
+        check knows which module it belongs to without changing the ``add``
+        signature module authors already use. Attribution is what lets the
+        dashboard show health per module rather than one global number.
+        """
+        self._current_owner = module_name
+
+    def add(self, check: HealthCheck) -> None:
+        if not check.module:
+            check.module = self._current_owner
+        self._checks.append(check)
+
+    @property
+    def all_checks(self) -> list[HealthCheck]:
+        """Every registered check, including on-demand ones.
+
+        Callers that poll on a timer want :attr:`probe_checks` instead.
+        """
+        return list(self._checks)
+
+    @property
+    def probe_checks(self) -> list[HealthCheck]:
+        """Checks safe to run automatically, on a timer."""
+        return [c for c in self._checks if c.probe]

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/menu.py

@@ -30,6 +30,15 @@ class MenuItem:
     requires_auth: bool = True
     roles: list[str] = field(default_factory=list)
     """Empty list = visible to all authenticated users."""
+    permissions: list[str] = field(default_factory=list)
+    """Permission keys required to see this entry. Empty = no permission check.
+
+    Declare the same permission the target route enforces. Roles alone cannot
+    express this: a custom role holding ``settings.view`` should see Settings,
+    and hard-coding ``roles=["admin"]`` would hide it from them while still
+    showing it to any admin-adjacent role that cannot actually open it. An
+    entry that 403s on click is worse than no entry at all.
+    """
     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)."""
@@ -69,12 +78,18 @@ class MenuRegistry:
         *,
         is_authenticated: bool,
         roles: list[str] | None = None,
+        permissions: list[str] | None = None,
     ) -> dict[str, list[dict]]:
-        """Return menu items grouped by section, filtered by auth/roles.
+        """Return menu items grouped by section, filtered by auth/roles/permissions.
+
+        ``permissions`` is the caller's already-expanded permission list (no
+        wildcards). Items declaring permissions the caller lacks are dropped,
+        so the sidebar never offers a screen that will 403 on click.
 
         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}
 
         for item in self.all_items:
@@ -82,6 +97,10 @@ class MenuRegistry:
                 continue
             if item.roles and not any(r in item.roles for r in roles):
                 continue
+            # All declared permissions must be held: an entry naming several is
+            # asking for all of them, matching how route guards compose.
+            if item.permissions and not granted.issuperset(item.permissions):
+                continue
             result[item.section.value].append(
                 {
                     "label": item.label,

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/module.py

@@ -10,6 +10,8 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from fastapi import APIRouter, FastAPI
 
+    from simple_module_core.audit_links import AuditLinkRegistry
+    from simple_module_core.csp import CspSourceRegistry
     from simple_module_core.design_packs import DesignPackRegistry
     from simple_module_core.events import EventBus
     from simple_module_core.feature_flags import FeatureFlagRegistry
@@ -147,6 +149,23 @@ class ModuleBase(ABC):
         mutations. Called once at boot, in dependency order.
         """
 
+    def register_csp_sources(self, registry: CspSourceRegistry) -> None:
+        """Declare external origins this module's frontend loads assets from.
+
+        The host ships a strict Content-Security-Policy; a module whose
+        pages pull a stylesheet, font, or API from another origin must
+        declare it here or the browser blocks the request::
+
+            def register_csp_sources(self, registry):
+                registry.add("style-src", "https://rsms.me")
+                registry.add("font-src", "https://rsms.me")
+
+        Only fetch directives can be extended (never default-src,
+        base-uri, form-action, frame-ancestors), and each source must be a
+        single origin/scheme token — invalid declarations raise at boot.
+        Called once, in dependency order.
+        """
+
     def register_design_packs(self, registry: DesignPackRegistry) -> None:
         """Declare design packs this module ships for the public site.
 
@@ -163,6 +182,28 @@ class ModuleBase(ABC):
         order.
         """
 
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        """Declare where this module's audited records can be viewed.
+
+        An audit entry stores a table name and a primary key, which tells the
+        reader what changed but gives them no way to open it. Override this
+        hook to make your module's rows reachable from the audit log::
+
+            def register_audit_links(self, registry):
+                registry.register(
+                    AuditLink(
+                        entity_type="users_user",
+                        url_template="/admin/users/{id}/edit",
+                        label="User",
+                    )
+                )
+
+        ``entity_type`` is the ``__tablename__`` the rows are audited under.
+        Registering only supplies the URL — the target route still enforces
+        its own permissions, so linking never widens access. Called once at
+        boot, in dependency order.
+        """
+
     def register_middleware(self, app: FastAPI) -> None:
         """Add middleware to the application.
 

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/simple_module_core/services.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
     from simple_module_db.session import DatabaseState
     from simple_module_hosting.settings import Settings
 
+    from simple_module_core.audit_links import AuditLinkRegistry
     from simple_module_core.design_packs import DesignPackRegistry
     from simple_module_core.events import EventBus
     from simple_module_core.feature_flags import FeatureFlagRegistry
@@ -44,6 +45,7 @@ class Services:
     health_registry: HealthRegistry
     public_routes: PublicRouteRegistry
     design_packs: DesignPackRegistry
+    audit_links: AuditLinkRegistry
     i18n_registry: I18nRegistry
     inertia_config: InertiaConfig
     modules: tuple[ModuleBase, ...]

simple_module_core-0.0.31/tests/test_audit_links.py

@@ -0,0 +1,57 @@
+"""Tests for AuditLink / AuditLinkRegistry.
+
+The audit log stores a table name and a primary key. This registry is how a
+module says where those rows can be opened, so the log stops being a wall of
+unactionable uuids.
+"""
+
+from __future__ import annotations
+
+import pytest
+from simple_module_core.audit_links import AuditLink, AuditLinkRegistry
+
+
+class TestAuditLink:
+    def test_url_for_substitutes_the_id(self):
+        link = AuditLink(entity_type="User", url_template="/users/admin/{id}")
+        assert link.url_for("a91f3c2b") == "/users/admin/a91f3c2b"
+
+    def test_template_without_placeholder_is_rejected(self):
+        """Every row would otherwise link to the same page."""
+        with pytest.raises(ValueError, match="contains no"):
+            AuditLink(entity_type="User", url_template="/users/admin")
+
+    def test_label_defaults_to_empty(self):
+        assert AuditLink(entity_type="t", url_template="/t/{id}").label == ""
+
+
+class TestAuditLinkRegistry:
+    def test_get_returns_none_for_unclaimed_tables(self):
+        """Join tables and blob stores have no screen; that is not an error."""
+        assert AuditLinkRegistry().get("UserPermission") is None
+
+    def test_register_and_get(self):
+        reg = AuditLinkRegistry()
+        link = AuditLink(entity_type="User", url_template="/users/admin/{id}", label="User")
+        reg.register(link)
+        assert reg.get("User") is link
+
+    def test_conflicting_claims_raise(self):
+        """Two modules mapping one table means one of them silently loses."""
+        reg = AuditLinkRegistry()
+        reg.register(AuditLink(entity_type="User", url_template="/a/{id}"))
+        with pytest.raises(ValueError, match="Two modules claim"):
+            reg.register(AuditLink(entity_type="User", url_template="/b/{id}"))
+
+    def test_registering_the_same_link_twice_is_allowed(self):
+        """Idempotent re-registration must not break a re-entrant boot."""
+        reg = AuditLinkRegistry()
+        for _ in range(2):
+            reg.register(AuditLink(entity_type="User", url_template="/a/{id}"))
+        assert len(reg.all_links) == 1
+
+    def test_all_links_is_a_copy(self):
+        reg = AuditLinkRegistry()
+        reg.register(AuditLink(entity_type="User", url_template="/a/{id}"))
+        reg.all_links.clear()
+        assert reg.get("User") is not None

simple_module_core-0.0.31/tests/test_csp_registry.py

@@ -0,0 +1,116 @@
+"""Modules can extend the host Content-Security-Policy with extra origins.
+
+Found in the field: the pagebuilder module's editor loads a stylesheet from
+``rsms.me``, which the framework CSP blocks — and there was no way for the
+module (or the host) to declare that origin short of patching the installed
+package. ``register_csp_sources`` closes that gap the same way
+``register_public_routes`` does for auth exemptions.
+"""
+
+from __future__ import annotations
+
+import pytest
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.csp import CspSourceError, CspSourceRegistry
+
+_POLICY = (
+    "default-src 'self'; "
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "
+    "font-src 'self' https://fonts.gstatic.com data:"
+)
+
+
+class TestRegistry:
+    def test_extends_existing_directive(self) -> None:
+        reg = CspSourceRegistry()
+        reg.add("style-src", "https://rsms.me")
+        out = reg.extend_policy(_POLICY)
+        assert (
+            "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://rsms.me" in out
+        )
+
+    def test_duplicate_and_already_present_sources_are_not_repeated(self) -> None:
+        reg = CspSourceRegistry()
+        reg.add("style-src", "https://rsms.me")
+        reg.add("style-src", "https://rsms.me")
+        reg.add("style-src", "https://fonts.googleapis.com")  # already in the policy
+        out = reg.extend_policy(_POLICY)
+        assert out.count("https://rsms.me") == 1
+        assert out.count("https://fonts.googleapis.com") == 1
+
+    def test_missing_directive_gets_self_plus_source(self) -> None:
+        """A brand-new clause must keep 'self', or it would *narrow* the policy:
+        without the clause the browser falls back to default-src 'self'."""
+        reg = CspSourceRegistry()
+        reg.add("connect-src", "https://api.example.com")
+        out = reg.extend_policy(_POLICY)
+        assert "connect-src 'self' https://api.example.com" in out
+
+    def test_missing_elem_directive_inherits_its_fallback_clause(self) -> None:
+        """style-src-elem falls back to style-src (not default-src): a fresh
+        clause must inherit style-src's sources, or creating it would silently
+        drop 'unsafe-inline' and the font origins from element styles."""
+        reg = CspSourceRegistry()
+        reg.add("style-src-elem", "https://rsms.me")
+        out = reg.extend_policy(_POLICY)
+        assert (
+            "style-src-elem 'self' 'unsafe-inline' https://fonts.googleapis.com https://rsms.me"
+            in out
+        )
+
+    def test_empty_registry_returns_policy_unchanged(self) -> None:
+        reg = CspSourceRegistry()
+        assert reg.extend_policy(_POLICY) == _POLICY
+        assert not reg
+
+    def test_unknown_directive_rejected(self) -> None:
+        reg = CspSourceRegistry()
+        with pytest.raises(CspSourceError, match="directive"):
+            reg.add("script-src-attr; evil", "https://x.example")
+
+    def test_injection_shaped_sources_rejected(self) -> None:
+        reg = CspSourceRegistry()
+        for bad in (
+            "https://x; script-src *",
+            "https://x 'unsafe-eval'",
+            "",
+            "'*'",
+            "https://a.example,https://b.example",  # comma would smuggle a 2nd policy
+            "*.",  # wildcard with no host
+        ):
+            with pytest.raises(CspSourceError):
+                reg.add("style-src", bad)
+
+    def test_base_directive_extras_reach_existing_elem_clause(self) -> None:
+        """`script-src-elem` shadows `script-src` once present: without the
+        mirror, a module's script-src origin never reaches <script> elements —
+        the very load it declared the origin for."""
+        reg = CspSourceRegistry()
+        reg.add("script-src", "https://cdn.example.com")
+        policy = "default-src 'self'; script-src 'self'; script-src-elem 'self' 'unsafe-inline'"
+        out = reg.extend_policy(policy)
+        assert "script-src 'self' https://cdn.example.com" in out
+        assert "script-src-elem 'self' 'unsafe-inline' https://cdn.example.com" in out
+
+    def test_child_src_extras_reach_existing_frame_and_worker_clauses(self) -> None:
+        """`frame-src` and `worker-src` shadow `child-src` once present (the
+        host default policy ships both): without the mirror, a module's
+        child-src origin would never apply to frames or workers — the loads
+        the fallback chain says child-src governs."""
+        reg = CspSourceRegistry()
+        reg.add("child-src", "https://embed.example")
+        policy = "default-src 'self'; frame-src 'self'; worker-src 'self' blob:"
+        out = reg.extend_policy(policy)
+        assert "frame-src 'self' https://embed.example" in out
+        assert "worker-src 'self' blob: https://embed.example" in out
+        assert "child-src 'self' https://embed.example" in out  # new clause, seeded
+
+
+class TestHook:
+    def test_register_csp_sources_is_a_noop_by_default(self) -> None:
+        class Quiet(ModuleBase):
+            meta = ModuleMeta(name="Quiet")
+
+        reg = CspSourceRegistry()
+        Quiet().register_csp_sources(reg)
+        assert not reg

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/tests/test_dotenv.py

@@ -7,10 +7,14 @@ here is hard to debug because it manifests as "the setting just isn't there".
 
 from __future__ import annotations
 
+import pathlib
+from pathlib import Path
+
 import pytest
 from simple_module_core.dotenv import (
     env_bool,
     env_str,
+    find_env_file,
     load_dotenv_into_environ,
     parse_dotenv,
 )
@@ -73,6 +77,23 @@ class TestParseDotenv:
         assert parse_dotenv() == {"CWD_KEY": "present"}
 
 
+class TestFindEnvFile:
+    def test_home_lookup_failure_skips_boundary_check(self, tmp_path, monkeypatch):
+        """``Path.home()`` raises ``RuntimeError`` when ``$HOME`` is unset and
+        the UID has no passwd entry (rootless containers). ``find_env_file``
+        must not propagate that — it just skips the home-boundary check and
+        keeps walking.
+        """
+
+        def _raise_runtime_error() -> Path:
+            raise RuntimeError("no home directory for this uid")
+
+        monkeypatch.setattr(pathlib.Path, "home", staticmethod(_raise_runtime_error))
+        monkeypatch.delenv("SM_PROJECT_ROOT", raising=False)
+        monkeypatch.chdir(tmp_path)
+        assert find_env_file() == Path(".env")
+
+
 class TestLoadDotenvIntoEnviron:
     def test_setdefault_semantics_preserves_existing_env(self, tmp_path, monkeypatch):
         """Real ``os.environ`` wins over file values — same precedence as uvicorn."""

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/tests/test_health_registry.py

@@ -33,6 +33,41 @@ class TestHealthRegistry:
         reg.add(HealthCheck(name="b", check=check_b))
         assert len(reg.all_checks) == 2
 
+    async def test_checks_are_attributed_to_the_owning_module(self):
+        """The dashboard shows health per module, which needs this attribution."""
+        reg = HealthRegistry()
+
+        async def check() -> HealthCheckResult:
+            return HealthCheckResult(status=HealthStatus.HEALTHY)
+
+        reg.set_owner("FileStorage")
+        reg.add(HealthCheck(name="s3", check=check))
+        reg.set_owner("BackgroundTasks")
+        reg.add(HealthCheck(name="broker", check=check))
+
+        owners = {c.name: c.module for c in reg.all_checks}
+        assert owners == {"s3": "FileStorage", "broker": "BackgroundTasks"}
+
+    async def test_explicit_module_survives_the_current_owner(self):
+        reg = HealthRegistry()
+
+        async def check() -> HealthCheckResult:
+            return HealthCheckResult(status=HealthStatus.HEALTHY)
+
+        reg.set_owner("Dashboard")
+        reg.add(HealthCheck(name="db", check=check, module="Users"))
+        assert reg.all_checks[0].module == "Users"
+
+    async def test_unowned_checks_have_no_module(self):
+        """Checks added outside a register_health_checks hook belong to nobody."""
+        reg = HealthRegistry()
+
+        async def check() -> HealthCheckResult:
+            return HealthCheckResult(status=HealthStatus.HEALTHY)
+
+        reg.add(HealthCheck(name="db", check=check))
+        assert reg.all_checks[0].module == ""
+
     async def test_check_result_defaults(self):
         result = HealthCheckResult(status=HealthStatus.HEALTHY)
         assert result.detail is None

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/tests/test_menu.py

@@ -114,3 +114,52 @@ class TestMenuRegistryAdvanced:
         result = reg.get_for_user(is_authenticated=True)
         groups = [i["group"] for i in result["sidebar"]]
         assert groups == ["Administration", "System"]
+
+
+class TestPermissionFiltering:
+    """An entry that 403s on click is worse than no entry at all.
+
+    Roles alone could not express this: hard-coding ``roles=["admin"]`` hides
+    the screen from a custom role that legitimately holds the permission, while
+    still showing it to admin-adjacent roles that cannot open it.
+    """
+
+    async def test_entry_hidden_without_the_permission(self):
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Settings", url="/settings/", permissions=["settings.view"]))
+        result = reg.get_for_user(is_authenticated=True, permissions=["users.manage"])
+        assert result["sidebar"] == []
+
+    async def test_entry_shown_with_the_permission(self):
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Settings", url="/settings/", permissions=["settings.view"]))
+        result = reg.get_for_user(is_authenticated=True, permissions=["settings.view"])
+        assert [i["label"] for i in result["sidebar"]] == ["Settings"]
+
+    async def test_permission_granted_by_a_custom_role_is_enough(self):
+        """No role check involved — holding the key is what matters."""
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Settings", url="/settings/", permissions=["settings.view"]))
+        result = reg.get_for_user(
+            is_authenticated=True, roles=["auditor"], permissions=["settings.view"]
+        )
+        assert len(result["sidebar"]) == 1
+
+    async def test_all_declared_permissions_are_required(self):
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="X", url="/x", permissions=["a.view", "a.manage"]))
+        assert reg.get_for_user(is_authenticated=True, permissions=["a.view"])["sidebar"] == []
+        both = reg.get_for_user(is_authenticated=True, permissions=["a.view", "a.manage"])
+        assert len(both["sidebar"]) == 1
+
+    async def test_no_declared_permissions_means_no_check(self):
+        """Existing entries must keep working without opting in."""
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Home", url="/"))
+        assert len(reg.get_for_user(is_authenticated=True, permissions=[])["sidebar"]) == 1
+
+    async def test_omitting_permissions_entirely_hides_gated_entries(self):
+        """A caller that passes no permissions holds none — fail closed."""
+        reg = MenuRegistry()
+        reg.add(MenuItem(label="Settings", url="/settings/", permissions=["settings.view"]))
+        assert reg.get_for_user(is_authenticated=True)["sidebar"] == []

{simple_module_core-0.0.30 → simple_module_core-0.0.31}/tests/test_services.py

@@ -31,6 +31,7 @@ class TestServices:
         assert s.health_registry is _SENTINEL_HEALTH
         assert s.public_routes is _SENTINEL_PUBLIC_ROUTES
         assert s.design_packs is _SENTINEL_DESIGN_PACKS
+        assert s.audit_links is _SENTINEL_AUDIT_LINKS
         assert s.i18n_registry is _SENTINEL_I18N
         assert s.inertia_config is _SENTINEL_INERTIA
         assert s.modules == ()
@@ -45,6 +46,7 @@ _SENTINEL_FLAGS = object()
 _SENTINEL_HEALTH = object()
 _SENTINEL_PUBLIC_ROUTES = object()
 _SENTINEL_DESIGN_PACKS = object()
+_SENTINEL_AUDIT_LINKS = object()
 _SENTINEL_I18N = object()
 _SENTINEL_INERTIA = object()
 
@@ -61,6 +63,7 @@ def _make_services() -> Services:
         health_registry=_SENTINEL_HEALTH,  # type: ignore[arg-type]
         public_routes=_SENTINEL_PUBLIC_ROUTES,  # type: ignore[arg-type]
         design_packs=_SENTINEL_DESIGN_PACKS,  # type: ignore[arg-type]
+        audit_links=_SENTINEL_AUDIT_LINKS,  # type: ignore[arg-type]
         i18n_registry=_SENTINEL_I18N,  # type: ignore[arg-type]
         inertia_config=_SENTINEL_INERTIA,  # type: ignore[arg-type]
         modules=(),

simple_module_core-0.0.30/simple_module_core/dotenv.py

@@ -1,69 +0,0 @@
-"""Minimal ``.env`` parser + env-var helpers — dependency-free.
-
-Used in places that can't or shouldn't pull in ``pydantic-settings`` (the
-diagnostics CLI runs before the host package is imported; the users-module
-bootstrap runs after settings are constructed and needs to read values that
-``UsersSettings`` deliberately omits from ``env_file``).
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-BOOL_LITERALS_TRUE = frozenset({"1", "true", "t", "yes", "y", "on"})
-BOOL_LITERALS_FALSE = frozenset({"0", "false", "f", "no", "n", "off"})
-
-
-def parse_dotenv(path: Path | None = None) -> dict[str, str]:
-    """Parse a ``.env`` file into a dict. Empty dict if the file is missing.
-
-    Values surrounded by matching single or double quotes have the quotes
-    stripped. Does *not* handle escapes, ``export KEY=…``, or multiline
-    values — keep the file simple. Does *not* mutate ``os.environ``; the
-    caller decides whether to merge.
-
-    Without ``path``, looks up ``$SM_PROJECT_ROOT/.env`` (falling back to
-    ``$CWD/.env``) — the convention used by every tool in this repo.
-    """
-    if path is None:
-        root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
-        path = root / ".env"
-    if not path.is_file():
-        return {}
-    parsed: dict[str, str] = {}
-    for raw in path.read_text(encoding="utf-8").splitlines():
-        line = raw.strip()
-        if not line or line.startswith("#") or "=" not in line:
-            continue
-        key, _, value = line.partition("=")
-        parsed[key.strip()] = value.strip().strip('"').strip("'")
-    return parsed
-
-
-def load_dotenv_into_environ(path: Path | None = None) -> None:
-    """Merge ``parse_dotenv(path)`` into ``os.environ`` via ``setdefault``.
-
-    Same precedence as the web process under uvicorn: real environment wins
-    over file values. Worker entrypoints call this before importing settings.
-    """
-    for key, value in parse_dotenv(path).items():
-        os.environ.setdefault(key, value)
-
-
-def env_str(name: str, default: str) -> str:
-    """Return ``$name`` if set and non-empty, else ``default``."""
-    value = os.environ.get(name, "").strip()
-    return value or default
-
-
-def env_bool(name: str, default: bool = False) -> bool:
-    """Parse ``$name`` as a boolean, returning ``default`` when unset/blank."""
-    raw = os.environ.get(name, "").strip().lower()
-    if not raw:
-        return default
-    if raw in BOOL_LITERALS_TRUE:
-        return True
-    if raw in BOOL_LITERALS_FALSE:
-        return False
-    return default

simple_module_core-0.0.30/simple_module_core/health.py

@@ -1,46 +0,0 @@
-"""Health check registry for module-contributed health checks."""
-
-from __future__ import annotations
-
-from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
-from enum import StrEnum
-
-
-class HealthStatus(StrEnum):
-    HEALTHY = "healthy"
-    DEGRADED = "degraded"
-    UNHEALTHY = "unhealthy"
-
-
-@dataclass
-class HealthCheckResult:
-    """Result of a single health check."""
-
-    status: HealthStatus
-    detail: str | None = None
-
-
-HealthCheckFn = Callable[[], Awaitable[HealthCheckResult]]
-
-
-@dataclass
-class HealthCheck:
-    """A named health check with an async callable."""
-
-    name: str
-    check: HealthCheckFn
-
-
-class HealthRegistry:
-    """Collects health checks contributed by modules."""
-
-    def __init__(self) -> None:
-        self._checks: list[HealthCheck] = []
-
-    def add(self, check: HealthCheck) -> None:
-        self._checks.append(check)
-
-    @property
-    def all_checks(self) -> list[HealthCheck]:
-        return list(self._checks)