simple-module-settings 0.0.30__tar.gz → 0.0.32__tar.gz

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/.gitignore

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

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simple_module_settings
-Version: 0.0.30
+Version: 0.0.32
 Summary: Runtime settings UI — modules plug their own settings panels into a shared admin view
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -21,9 +21,9 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: simple-module-core==0.0.30
-Requires-Dist: simple-module-db==0.0.30
-Requires-Dist: simple-module-hosting==0.0.30
+Requires-Dist: simple-module-core==0.0.32
+Requires-Dist: simple-module-db==0.0.32
+Requires-Dist: simple-module-hosting==0.0.32
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_settings"
-version = "0.0.30"
+version = "0.0.32"
 description = "Runtime settings UI — modules plug their own settings panels into a shared admin view"
 readme = "README.md"
 license = "MIT"
@@ -21,9 +21,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.30",
-    "simple_module_db==0.0.30",
-    "simple_module_hosting==0.0.30",
+    "simple_module_core==0.0.32",
+    "simple_module_db==0.0.32",
+    "simple_module_hosting==0.0.32",
     "typer>=0.12",
 ]
 

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/settings/_module_settings.py

@@ -6,15 +6,18 @@ Each module stores a services dataclass on ``app.state.<package>`` whose
 
 from __future__ import annotations
 
+import os
 import re
 from dataclasses import dataclass
 from typing import Any
 
 from fastapi import FastAPI
+from fastapi.encoders import jsonable_encoder
 from pydantic_settings import BaseSettings
 
 from settings.env_vars import env_prefix_for
 from settings.hydrate import value_type_for_field
+from settings.service import SettingService
 
 # We intentionally DON'T match the bare word "token" (would mask
 # `verification_token_lifetime_seconds` — just an int) or "key" alone (would
@@ -41,6 +44,37 @@ class ModuleSettingField:
     type: str
     requires_restart: bool
     group: str | None
+    env_set: bool = False
+    """This field is genuinely env-readable *and* its env var is set.
+
+    Deliberately not "the ``SM_*`` label below is present in ``os.environ``".
+    The bundled module settings classes declare no ``env_prefix`` — they are
+    constructed from pydantic defaults and hydrated from the DB — so their
+    ``SM_*`` vars are never consulted. Reporting a leftover
+    ``SM_USERS_SMTP_HOST`` as the live source would invert the very question
+    this screen answers. Classes that *do* declare one (the host's ``Settings``
+    with ``SM_``, and anything from the module scaffold) report ``env`` for
+    real, because for them pydantic really does read it.
+    """
+    db_override: bool = False
+    """A stored setting overrides this field."""
+
+    @property
+    def source(self) -> str:
+        """Where the live value came from: ``db``, ``env`` or ``default``.
+
+        Mirrors the precedence in ``hydrate_settings``: DB overrides are passed
+        to the constructor explicitly, so they beat anything pydantic reads for
+        fields left unset, which in turn beats the field default. ``env`` only
+        appears for settings classes that actually declare an ``env_prefix``;
+        see :attr:`env_set`. Showing this is the difference between "why is
+        this not taking effect" being a five-minute question and an afternoon.
+        """
+        if self.db_override:
+            return "db"
+        if self.env_set:
+            return "env"
+        return "default"
 
 
 @dataclass(frozen=True, slots=True)
@@ -93,16 +127,43 @@ def _resolve_default(info) -> Any:
     return None
 
 
-def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSettingField:
+def _env_readable_var(settings: BaseSettings, name: str) -> str | None:
+    """Env var pydantic would actually read for ``name``, or ``None``.
+
+    ``env_var`` on the view is a *label* — the ``SM_<PACKAGE>_<FIELD>`` name the
+    ``smpy settings import-from-env`` CLI looks for, kept from before settings
+    moved into the DB. It is not evidence that pydantic reads it: the bundled
+    module settings classes declare ``SettingsConfigDict(extra="ignore")`` with
+    no ``env_prefix``, so ``SM_FILE_STORAGE_BACKEND`` has no effect on
+    ``FileStorageSettings()``. Deriving env-readability from the class's own
+    ``env_prefix`` keeps the "From environment" badge honest, and works as-is
+    for the classes that do declare one — the host's ``Settings`` (``SM_``) and
+    every module built from the scaffold, whose template ships
+    ``env_prefix="SM_<PACKAGE>_"``.
+    """
+    env_prefix = str(type(settings).model_config.get("env_prefix") or "")
+    if not env_prefix:
+        return None
+    return f"{env_prefix}{name.upper()}"
+
+
+def _field_view(
+    name: str,
+    settings: BaseSettings,
+    prefix: str,
+    overridden: frozenset[str] = frozenset(),
+) -> ModuleSettingField:
     cls = type(settings)
     info = cls.model_fields[name]
     raw_value = getattr(settings, name)
     secret = is_secret_field(name)
     extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
     default = _resolve_default(info)
+    env_var = f"{prefix}{name.upper()}"
+    live_env_var = _env_readable_var(settings, name)
     return ModuleSettingField(
         name=name,
-        env_var=f"{prefix}{name.upper()}",
+        env_var=env_var,
         value=_mask(raw_value) if secret else raw_value,
         default=_mask(default) if secret else default,
         description=info.description or "",
@@ -110,16 +171,26 @@ def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSetting
         type=value_type_for_field(cls, name),
         requires_restart=bool(extra.get("requires_restart", False)),
         group=extra.get("group"),
+        env_set=live_env_var is not None and live_env_var in os.environ,
+        db_override=name in overridden,
     )
 
 
-def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
+def collect_module_settings(
+    app: FastAPI,
+    overrides: dict[str, frozenset[str]] | None = None,
+) -> list[ModuleSettingsView]:
     """Return a sorted, serializable view of every module's BaseSettings.
 
     Folds in both ``app.state.sm.modules`` (plugin modules) and additional
     packages registered via ``app.state.settings.module_registry`` (e.g.
     ``"host"``) that aren't backed by a ``ModuleBase`` instance.
+
+    ``overrides`` maps package -> field names carrying a stored override. It
+    is passed in rather than read here because fetching it is async and this
+    function is not; callers without it get ``db_override=False`` throughout.
     """
+    by_package = overrides or {}
     views: list[ModuleSettingsView] = []
     seen: set[str] = set()
 
@@ -128,7 +199,7 @@ def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
         settings = _extract_settings(app, package)
         if settings is None:
             continue
-        views.append(_build_view(mod.meta.name, package, settings))
+        views.append(_build_view(mod.meta.name, package, settings, by_package))
         seen.add(package)
 
     settings_services = getattr(app.state, "settings", None)
@@ -140,16 +211,24 @@ def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
             settings = _extract_settings(app, package)
             if settings is None:
                 continue
-            views.append(_build_view(package.title(), package, settings))
+            views.append(_build_view(package.title(), package, settings, by_package))
             seen.add(package)
 
     views.sort(key=lambda v: v.module_name)
     return views
 
 
-def _build_view(module_name: str, package: str, settings: BaseSettings) -> ModuleSettingsView:
+def _build_view(
+    module_name: str,
+    package: str,
+    settings: BaseSettings,
+    overrides: dict[str, frozenset[str]] | None = None,
+) -> ModuleSettingsView:
     prefix = env_prefix_for(package)
-    fields = [_field_view(name, settings, prefix) for name in type(settings).model_fields]
+    overridden = (overrides or {}).get(package, frozenset())
+    fields = [
+        _field_view(name, settings, prefix, overridden) for name in type(settings).model_fields
+    ]
     return ModuleSettingsView(
         module_name=module_name,
         package=package,
@@ -159,8 +238,29 @@ def _build_view(module_name: str, package: str, settings: BaseSettings) -> Modul
     )
 
 
+async def overrides_by_package(service: SettingService) -> dict[str, frozenset[str]]:
+    """Map package -> field names carrying a stored override.
+
+    Reads the SYSTEM scope once and buckets by key prefix. Packages with no
+    overrides are simply absent, which :func:`collect_module_settings` already
+    treats as "nothing overridden". Shared by both the Inertia view and the
+    JSON API so the two never drift on what "overridden" means.
+    """
+    from settings.store import SettingsStore
+
+    return await SettingsStore(service).all_override_fields()
+
+
 def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
-    """Convert dataclass views to plain dicts for Inertia props."""
+    """Convert dataclass views to plain dicts for Inertia props.
+
+    Field values arrive as whatever type the module declared — pydantic has
+    already coerced ``media_root: Path`` to a ``PosixPath``, ``timeout:
+    timedelta`` to a ``timedelta`` — and this screen reflects every installed
+    module's settings, so the set of types is open-ended by design. They are
+    encoded here rather than handed on as-is: this is the boundary where a
+    settings object stops being Python and becomes a prop.
+    """
     return [
         {
             "module_name": v.module_name,
@@ -171,13 +271,16 @@ def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
                 {
                     "name": f.name,
                     "env_var": f.env_var,
-                    "value": f.value,
-                    "default": f.default,
+                    "value": jsonable_encoder(f.value),
+                    "default": jsonable_encoder(f.default),
                     "description": f.description,
                     "is_secret": f.is_secret,
                     "type": f.type,
                     "requires_restart": f.requires_restart,
                     "group": f.group,
+                    "env_set": f.env_set,
+                    "db_override": f.db_override,
+                    "source": f.source,
                 }
                 for f in v.fields
             ],

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/settings/constants.py

@@ -48,6 +48,12 @@ VIEW_PREFIX: Final = "/settings"
 VIEW_CREATE_PATH: Final = "/create"
 VIEW_EDIT_PATH: Final = "/{setting_id}/edit"
 VIEW_MODULES_PATH: Final = "/modules"
+"""Legacy path for the per-module forms. Those now live at the section root;
+this redirects, so existing links and bookmarks keep working."""
+
+VIEW_STORE_PATH: Final = "/store"
+"""Raw key/value store. Demoted from the section root: it is a database view,
+and an admin looking for "settings" almost always wants the module forms."""
 API_BY_ID_PATH: Final = "/{setting_id}"
 API_BY_KEY_PATH: Final = "/by-key/{key}"
 API_RESOLVE_PATH: Final = "/resolve/{key}"

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/settings/endpoints/module_api.py

@@ -17,6 +17,7 @@ from settings._module_settings import (
     SECRET_MASK,
     collect_module_settings,
     is_secret_field,
+    overrides_by_package,
     serialize,
 )
 from settings.constants import MODULE_PACKAGE, PERM_DELETE, PERM_EDIT, PERM_VIEW
@@ -47,8 +48,15 @@ def _strip_mask_sentinels(changes: dict[str, Any]) -> dict[str, Any]:
 
 
 @router.get("", dependencies=_VIEW)
-async def list_modules(request: Request) -> dict[str, Any]:
-    views = collect_module_settings(request.app)
+async def list_modules(
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> dict[str, Any]:
+    # Match the Inertia ModulesEdit view: without the overrides map, every
+    # field's `source`/`db_override` would report env/default even when a
+    # stored override is actually in force.
+    overrides = await overrides_by_package(service)
+    views = collect_module_settings(request.app, overrides)
     return {"modules": serialize(views)}
 
 

simple_module_settings-0.0.32/settings/endpoints/views.py

@@ -0,0 +1,272 @@
+"""Inertia view endpoints for the Settings module.
+
+Page component identifiers are file-private module constants — same pattern
+the dashboard/users/feature_flags views use. The diagnostic ``SM003``
+matches the resolved literal value, not the source-level expression, so a
+named constant is fine; ``test_settings_module.py`` cross-checks that the
+strings below match what ``pages/*.tsx`` declare.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from inertia import InertiaResponse
+from pydantic import ValidationError
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.inertia_utils import redirect_back_with_errors, validation_errors_to_dict
+from simple_module_hosting.permissions import RequiresPermission
+from starlette.responses import RedirectResponse
+
+from settings._module_settings import (
+    _package_of,
+    collect_module_settings,
+    overrides_by_package,
+    serialize,
+)
+from settings.constants import (
+    ERR_SETTING_NOT_FOUND,
+    PERM_CREATE,
+    PERM_DELETE,
+    PERM_EDIT,
+    PERM_VIEW,
+    PROP_ERROR,
+    PROP_MODULES,
+    PROP_SETTING,
+    PROP_SETTINGS,
+    VIEW_CREATE_PATH,
+    VIEW_EDIT_PATH,
+    VIEW_MODULES_PATH,
+    VIEW_STORE_PATH,
+)
+from settings.contracts.schemas import SettingCreate, SettingUpdate
+from settings.deps import get_setting_service
+from settings.service import SettingService
+
+_PAGE_BROWSE = "Settings/Browse"
+_PAGE_CREATE = "Settings/Create"
+_PAGE_EDIT = "Settings/Edit"
+_PAGE_MODULES_EDIT = "Settings/ModulesEdit"
+
+# Row-level actions return to the raw store they were performed in, not to
+# the module forms that now own the section root.
+_REDIRECT_SETTINGS = "/settings/store"
+_REDIRECT_MODULES = "/settings/"
+
+# Every screen in this section reads configuration: module field values,
+# their env var names, and now which of the two is in force. The matching JSON
+# API (``/api/settings/...``) has always required ``settings.view``, so leaving
+# these unguarded let any signed-in account read the same data by asking for
+# the page instead. Mutating routes add their own stricter guard on top.
+router = APIRouter(dependencies=[Depends(RequiresPermission(PERM_VIEW))])
+
+
+@router.get(VIEW_STORE_PATH, response_model=None)
+async def browse(
+    inertia: InertiaDep,
+    service: SettingService = Depends(get_setting_service),
+) -> InertiaResponse:
+    """The raw key/value store.
+
+    Moved off the section root: it is a database view, and an admin who clicks
+    "Settings" is nearly always after a module's form, not a table of rows
+    keyed by dotted strings.
+    """
+    items = await service.list_all()
+    return await inertia.render(
+        _PAGE_BROWSE,
+        {PROP_SETTINGS: [item.model_dump(mode="json") for item in items]},
+    )
+
+
+@router.get(VIEW_MODULES_PATH, response_model=None)
+async def modules_redirect() -> RedirectResponse:
+    """The per-module forms moved to the section root; keep old links alive."""
+    return RedirectResponse(_REDIRECT_MODULES, status_code=308)
+
+
+@router.get(VIEW_CREATE_PATH, response_model=None)
+async def create_view(request: Request, inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(_PAGE_CREATE, {"known_keys": _known_keys(request)})
+
+
+def _known_keys(request: Request) -> list[dict[str, str]]:
+    """Every ``<package>.<field>`` a module actually reads, for autocomplete.
+
+    The key field is free text, and a typo produces a row that looks saved and
+    is silently never read — the failure gives no feedback at all. Suggesting
+    the registered keys makes the common case unmissable without forbidding
+    the uncommon one: keys outside this list stay valid, since a module can
+    read settings the settings module cannot enumerate.
+    """
+    suggestions: list[dict[str, str]] = []
+    for view in collect_module_settings(request.app):
+        for field in view.fields:
+            suggestions.append(
+                {
+                    "key": f"{view.package}.{field.name}",
+                    "type": field.type,
+                    "description": field.description,
+                    "module": view.module_name,
+                }
+            )
+    return sorted(suggestions, key=lambda s: s["key"])
+
+
+@router.get(VIEW_EDIT_PATH, response_model=None)
+async def edit_view(
+    setting_id: int,
+    inertia: InertiaDep,
+    service: SettingService = Depends(get_setting_service),
+) -> InertiaResponse:
+    item = await service.get_by_id(setting_id)
+    if item is None:
+        return await inertia.render(_PAGE_BROWSE, {PROP_ERROR: ERR_SETTING_NOT_FOUND})
+    return await inertia.render(_PAGE_EDIT, {PROP_SETTING: item.model_dump(mode="json")})
+
+
+# ── Form actions (POST/PUT/DELETE → redirect) ─────────────────
+
+
+# Posts to the store collection, which is where the rows live now that the
+# section root renders the module forms.
+@router.post(
+    VIEW_STORE_PATH,
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_CREATE))],
+)
+async def create_action(
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> RedirectResponse:
+    body = await request.json()
+    try:
+        data = SettingCreate(**body)
+    except ValidationError as exc:
+        return redirect_back_with_errors(request, validation_errors_to_dict(exc))
+    await service.create(data)
+    return RedirectResponse(_REDIRECT_SETTINGS, status_code=303)
+
+
+@router.put(
+    "/{setting_id}",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_EDIT))],
+)
+async def update_action(
+    setting_id: int,
+    request: Request,
+    service: SettingService = Depends(get_setting_service),
+) -> RedirectResponse:
+    body = await request.json()
+    try:
+        data = SettingUpdate(**body)
+    except ValidationError as exc:
+        return redirect_back_with_errors(request, validation_errors_to_dict(exc))
+    await service.update(setting_id, data)
+    return RedirectResponse(_REDIRECT_SETTINGS, status_code=303)
+
+
+@router.delete(
+    "/{setting_id}",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_DELETE))],
+)
+async def delete_action(
+    setting_id: int,
+    service: SettingService = Depends(get_setting_service),
+) -> RedirectResponse:
+    await service.delete(setting_id)
+    return RedirectResponse(_REDIRECT_SETTINGS, status_code=303)
+
+
+@router.get("/", response_model=None)
+async def modules_view(
+    request: Request,
+    inertia: InertiaDep,
+    service: SettingService = Depends(get_setting_service),
+) -> InertiaResponse:
+    """Read-only view of every module's pydantic ``BaseSettings`` instance.
+
+    Auto-discovered from ``app.state.sm.modules``; secrets are masked server-side.
+    Each field also reports where its live value came from — a stored override,
+    an ``SM_*`` env var, or the field default — so a setting that "isn't taking
+    effect" explains itself.
+    """
+    overrides = await overrides_by_package(service)
+    views = collect_module_settings(request.app, overrides)
+    return await inertia.render(
+        _PAGE_MODULES_EDIT,
+        {
+            PROP_MODULES: serialize(views),
+            # Which packages can be connection-tested, so the page only offers
+            # the button where something is actually reachable.
+            "testable": _testable_packages(request),
+        },
+    )
+
+
+def _testable_packages(request: Request) -> list[str]:
+    """Packages whose module registered at least one health check.
+
+    "Test connection" is just that module's health checks run on demand —
+    reusing the registry means settings never learns what an SMTP or an S3
+    connection is.
+    """
+    registry = request.app.state.sm.health_registry
+    owners = {c.module for c in registry.all_checks if c.module}
+    return sorted(
+        {
+            _package_of(mod)
+            for mod in getattr(request.app.state.sm, "modules", ())
+            if mod.meta.name in owners
+        }
+    )
+
+
+@router.post(
+    "/test-connection/{package}",
+    response_model=None,
+    # Guarded, unlike the read-only view routes around it: this one makes the
+    # server open outbound connections on demand (SMTP AUTH, S3) and hands the
+    # raw failure text — hostnames, bucket names, auth errors — back to the
+    # caller. Only someone allowed to change these settings should be able to.
+    dependencies=[Depends(RequiresPermission(PERM_EDIT))],
+)
+async def test_connection(package: str, request: Request) -> dict:
+    """Run one module's health checks now and report each result.
+
+    Returns 200 with per-check results even when a check fails: an admin
+    testing a connection expects to read the failure, not to get an error
+    status with the reason buried.
+    """
+    modules = getattr(request.app.state.sm, "modules", ())
+    owner = next((m for m in modules if _package_of(m) == package), None)
+    if owner is None:
+        raise HTTPException(status_code=404, detail=f"Unknown module package: {package}")
+
+    checks = [
+        c for c in request.app.state.sm.health_registry.all_checks if c.module == owner.meta.name
+    ]
+    if not checks:
+        raise HTTPException(status_code=404, detail=f"{owner.meta.name} has no connection to test")
+
+    # Run independently of one another — a module can register several checks
+    # (e.g. SMTP + primary storage + backup storage), and sequentially awaiting
+    # each one would block the request for the sum of their latencies instead
+    # of the slowest one, the same reasoning dashboard.stats._run_health_checks
+    # already applies to probe checks.
+    async def _run_one(check) -> dict:
+        try:
+            outcome = await check.check()
+            return {
+                "name": check.name,
+                "status": outcome.status.value,
+                "detail": outcome.detail or "",
+            }
+        except Exception as exc:
+            return {"name": check.name, "status": "unhealthy", "detail": str(exc)}
+
+    results = await asyncio.gather(*[_run_one(c) for c in checks])
+    return {"module": owner.meta.name, "checks": results}

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/settings/locales/en.json

@@ -39,7 +39,8 @@
     "value_label": "Value",
     "value_placeholder": "Enter a value",
     "description_label": "Description",
-    "description_placeholder": "Optional description"
+    "description_placeholder": "Optional description",
+    "key_unknown_warning": "No installed module declares this key. It will be stored, but nothing will read it unless a module looks it up."
   },
   "create": {
     "title": "New Setting",
@@ -66,6 +67,16 @@
       "value": "Value",
       "default": "Default",
       "description": "Description"
-    }
+    },
+    "test_connection": "Test connection",
+    "testing": "Testing…",
+    "env_var_hint": "Environment variable name for this field, used by \"smpy settings import-from-env\"",
+    "source_db": "Stored override",
+    "source_db_hint": "A stored setting supplies this value",
+    "source_db_over_env": "Stored (shadows env)",
+    "source_db_shadows_env": "A stored setting overrides {env_var}; the environment value is ignored",
+    "source_env": "From environment",
+    "source_env_hint": "{env_var} is set in this deployment",
+    "source_default": "Default"
   }
 }

{simple_module_settings-0.0.30 → simple_module_settings-0.0.32}/settings/module.py

@@ -6,6 +6,7 @@ import importlib.resources
 from pathlib import Path
 
 from fastapi import APIRouter, FastAPI
+from simple_module_core.audit_links import AuditLink, AuditLinkRegistry
 from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
@@ -21,6 +22,7 @@ from settings.constants import (
     MODULE_NAME,
     MODULE_PACKAGE,
     PERM_GROUP,
+    PERM_VIEW,
     VIEW_PREFIX,
 )
 
@@ -67,12 +69,27 @@ class SettingsModule(ModuleBase):
                 order=MENU_ORDER,
                 section=MenuSection.SIDEBAR,
                 group="System",
+                # Mirrors the view router's guard, so the entry is not offered
+                # to accounts whose click would 403.
+                permissions=[PERM_VIEW],
             )
         )
 
     def register_permissions(self, registry: PermissionRegistry) -> None:
         registry.add_group(PERM_GROUP, list(ALL_PERMISSIONS))
 
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        from settings.models import Setting
+
+        registry.register(
+            AuditLink(
+                # Class name, not __tablename__ — see AuditLink.entity_type.
+                entity_type=Setting.__name__,
+                url_template=f"{VIEW_PREFIX}/{{id}}/edit",
+                label="Setting",
+            )
+        )
+
     def locale_dirs(self) -> dict[str, Path]:
         base = Path(str(importlib.resources.files(__package__) / "locales"))
         return {LOCALE_NAMESPACE: base}