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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_settings
-Version: 0.0.32
+Version: 0.0.34
 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.32
-Requires-Dist: simple-module-db==0.0.32
-Requires-Dist: simple-module-hosting==0.0.32
+Requires-Dist: simple-module-core==0.0.34
+Requires-Dist: simple-module-db==0.0.34
+Requires-Dist: simple-module-hosting==0.0.34
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_settings-0.0.32 → simple_module_settings-0.0.34}/package.json

@@ -12,5 +12,7 @@
   "devDependencies": {
     "@simple-module-py/tsconfig": "*"
   },
-  "dependencies": {}
+  "dependencies": {
+    "sonner": "^2.0.7"
+  }
 }

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

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_settings"
-version = "0.0.32"
+version = "0.0.34"
 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.32",
-    "simple_module_db==0.0.32",
-    "simple_module_hosting==0.0.32",
+    "simple_module_core==0.0.34",
+    "simple_module_db==0.0.34",
+    "simple_module_hosting==0.0.34",
     "typer>=0.12",
 ]
 

simple_module_settings-0.0.34/settings/_field_meta.py

@@ -0,0 +1,81 @@
+"""Pure metadata readers for a single pydantic settings field.
+
+Split out of ``_module_settings`` so that file keeps one job — walking the app
+for settings classes — while the fiddly "what did pydantic actually record for
+this field?" questions live together and are testable without a FastAPI app.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+# ``^(console|smtp)$`` and nothing more adventurous: an alternation of literals
+# anchored at both ends is the only pattern shape that maps cleanly onto a
+# select. Anything else (character classes, quantifiers, sub-groups) stays a
+# free-text input rather than becoming a list that silently omits valid values.
+_ENUM_PATTERN = re.compile(r"^\^\(([^()|]+(?:\|[^()|]+)+)\)\$$")
+
+
+def resolve_default(info) -> Any:
+    """Return the effective default, handling ``default_factory`` fields.
+
+    Pydantic sets ``info.default`` to ``PydanticUndefined`` when
+    ``default_factory`` is used. We call the factory to get the concrete
+    default so the settings UI can serialize it.
+    """
+    from pydantic_core import PydanticUndefined
+
+    if info.default is not PydanticUndefined:
+        return info.default
+    if info.default_factory is not None:
+        return info.default_factory()
+    return None
+
+
+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 subclass ``DbBackedSettings``, which drops the env
+    source entirely, so ``SM_FILE_STORAGE_BACKEND`` has no effect on
+    ``FileStorageSettings()``. (Until GH #283 those classes subclassed
+    ``BaseSettings`` and merely omitted ``env_prefix``, which left pydantic
+    reading each field from its *bare* name instead of not at all.) 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_``), ``BackgroundTasksSettings``
+    (``SM_BG_TASKS_``), 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 choices_for(info) -> list[str] | None:
+    """The closed set of values this field accepts, or ``None`` if open.
+
+    Read from an explicit ``json_schema_extra={"choices": [...]}`` first, then
+    inferred from a simple alternation ``pattern``. A field constrained to
+    ``console`` or ``smtp`` renders as a select; without this it is a text box
+    whose only feedback on a typo is a 422 after Save.
+    """
+    extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
+    declared = extra.get("choices")
+    if isinstance(declared, (list, tuple)) and declared:
+        return [str(choice) for choice in declared]
+
+    for constraint in info.metadata:
+        pattern = getattr(constraint, "pattern", None)
+        if not isinstance(pattern, str):
+            continue
+        match = _ENUM_PATTERN.match(pattern)
+        if match:
+            return match.group(1).split("|")
+    return None

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

@@ -7,31 +7,28 @@ 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._field_meta import choices_for, env_readable_var, resolve_default
+
+# Re-exported: callers reach for ``SECRET_MASK`` / ``is_secret_field`` here.
+from settings._secrets import (  # noqa: F401
+    _NEVER_SECRET_TYPES,
+    SECRET_MASK,
+    conceals_secret,
+    embeds_credential,
+    is_named_secret,
+    is_secret_field,
+    mask,
+)
 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
-# mask `s3_bucket_key_prefix`). Only fragments that actually indicate material.
-_SECRET_PATTERNS = re.compile(
-    r"(password|secret|api[_-]?key|private[_-]?key|token[_-]?secret)", re.I
-)
-SECRET_MASK = "••••••••"
-
-
-def is_secret_field(name: str) -> bool:
-    """True if a field name suggests it holds credential material."""
-    return bool(_SECRET_PATTERNS.search(name))
-
 
 @dataclass(frozen=True, slots=True)
 class ModuleSettingField:
@@ -58,6 +55,22 @@ class ModuleSettingField:
     """
     db_override: bool = False
     """A stored setting overrides this field."""
+    env_readable: bool = False
+    """The declaring class reads env at all, i.e. it declares an ``env_prefix``.
+
+    :attr:`env_set` collapses two very different answers into one ``False``:
+    "there is no env fallback for this field" and "there is one and nobody set
+    it". The Resolved value panel has to tell them apart, or it labels a row
+    "env fallback" for a class that will never look at the environment.
+    """
+    env_value: str | None = None
+    """The env var's current contents, masked for secrets, or ``None``.
+
+    Only populated when the field is genuinely env-readable *and* set — it is
+    the fallback the panel shows, not a second copy of the live value.
+    """
+    choices: list[str] | None = None
+    """Closed set of accepted values, or ``None`` when the field is free text."""
 
     @property
     def source(self) -> str:
@@ -84,12 +97,9 @@ class ModuleSettingsView:
     env_prefix: str
     class_name: str
     fields: list[ModuleSettingField]
-
-
-def _mask(value: Any) -> Any:
-    if value in (None, "", [], {}):
-        return value
-    return SECRET_MASK
+    manage_url: str | None = None
+    """The module's own management page. When set, the generic editor renders
+    a link there instead of a second editor for the same fields."""
 
 
 def _package_of(mod: Any) -> str:
@@ -111,42 +121,6 @@ def _extract_settings(app: FastAPI, package: str) -> BaseSettings | None:
     return inner if isinstance(inner, BaseSettings) else None
 
 
-def _resolve_default(info) -> Any:
-    """Return the effective default, handling ``default_factory`` fields.
-
-    Pydantic sets ``info.default`` to ``PydanticUndefined`` when
-    ``default_factory`` is used. We call the factory to get the concrete
-    default so the settings UI can serialize it.
-    """
-    from pydantic_core import PydanticUndefined
-
-    if info.default is not PydanticUndefined:
-        return info.default
-    if info.default_factory is not None:
-        return info.default_factory()
-    return None
-
-
-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,
@@ -156,23 +130,42 @@ def _field_view(
     cls = type(settings)
     info = cls.model_fields[name]
     raw_value = getattr(settings, name)
-    secret = is_secret_field(name)
+    value_type = value_type_for_field(cls, name)
+    named_secret = is_named_secret(name, value_type)
     extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
-    default = _resolve_default(info)
+    default = resolve_default(info)
     env_var = f"{prefix}{name.upper()}"
-    live_env_var = _env_readable_var(settings, name)
+    live_env_var = env_readable_var(settings, name)
+    env_set = live_env_var is not None and live_env_var in os.environ
+    # ``live_env_var`` is not None whenever env_set is True, but the narrowing
+    # is spelled out so a future edit cannot turn this into ``os.environ[None]``.
+    raw_env = os.environ[live_env_var] if env_set and live_env_var is not None else None
+
+    def hidden(value: Any) -> bool:
+        return conceals_secret(name, value, value_type)
+
+    # ``is_secret`` drives the editor's input type and the "reveal" affordance,
+    # so it has to be true when *any* of the three readings is being hidden —
+    # otherwise the form offers to edit a value it is showing as dots.
+    secret = named_secret or any(embeds_credential(v) for v in (raw_value, default, raw_env))
     return ModuleSettingField(
         name=name,
         env_var=env_var,
-        value=_mask(raw_value) if secret else raw_value,
-        default=_mask(default) if secret else default,
+        value=mask(raw_value) if hidden(raw_value) else raw_value,
+        default=mask(default) if hidden(default) else default,
         description=info.description or "",
         is_secret=secret,
-        type=value_type_for_field(cls, name),
+        type=value_type,
         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,
+        env_set=env_set,
         db_override=name in overridden,
+        env_readable=live_env_var is not None,
+        # Masked on the same rule as ``value`` and ``default``: a secret stays
+        # hidden, everything else is shown. Masking unconditionally turned the
+        # Resolved value panel's env row into a row of dots for every key.
+        env_value=(mask(raw_env) if hidden(raw_env) else raw_env) if raw_env is not None else None,
+        choices=choices_for(info),
     )
 
 
@@ -194,16 +187,22 @@ def collect_module_settings(
     views: list[ModuleSettingsView] = []
     seen: set[str] = set()
 
+    settings_services = getattr(app.state, "settings", None)
+    registry = getattr(settings_services, "module_registry", None)
+
+    def _manage_url(package: str) -> str | None:
+        return registry.manage_url(package) if registry is not None else None
+
     for mod in getattr(app.state.sm, "modules", ()):
         package = _package_of(mod)
         settings = _extract_settings(app, package)
         if settings is None:
             continue
-        views.append(_build_view(mod.meta.name, package, settings, by_package))
+        views.append(
+            _build_view(mod.meta.name, package, settings, by_package, _manage_url(package))
+        )
         seen.add(package)
 
-    settings_services = getattr(app.state, "settings", None)
-    registry = getattr(settings_services, "module_registry", None)
     if registry is not None:
         for package in registry.all_packages():
             if package in seen:
@@ -211,7 +210,9 @@ def collect_module_settings(
             settings = _extract_settings(app, package)
             if settings is None:
                 continue
-            views.append(_build_view(package.title(), package, settings, by_package))
+            views.append(
+                _build_view(package.title(), package, settings, by_package, _manage_url(package))
+            )
             seen.add(package)
 
     views.sort(key=lambda v: v.module_name)
@@ -223,6 +224,7 @@ def _build_view(
     package: str,
     settings: BaseSettings,
     overrides: dict[str, frozenset[str]] | None = None,
+    manage_url: str | None = None,
 ) -> ModuleSettingsView:
     prefix = env_prefix_for(package)
     overridden = (overrides or {}).get(package, frozenset())
@@ -235,6 +237,7 @@ def _build_view(
         env_prefix=prefix,
         class_name=type(settings).__name__,
         fields=fields,
+        manage_url=manage_url,
     )
 
 
@@ -249,41 +252,3 @@ async def overrides_by_package(service: SettingService) -> dict[str, frozenset[s
     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.
-
-    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,
-            "package": v.package,
-            "env_prefix": v.env_prefix,
-            "class_name": v.class_name,
-            "fields": [
-                {
-                    "name": f.name,
-                    "env_var": f.env_var,
-                    "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
-            ],
-        }
-        for v in views
-    ]

simple_module_settings-0.0.34/settings/_module_settings_props.py

@@ -0,0 +1,56 @@
+"""Serialize module-settings views into Inertia props.
+
+Split from ``_module_settings`` (collection) so each file keeps one
+responsibility: that one discovers and shapes the views, this one is the
+boundary where a settings object stops being Python and becomes a prop.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+
+from settings._module_settings import ModuleSettingsView
+
+
+def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
+    """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.
+    """
+    return [
+        {
+            "module_name": v.module_name,
+            "package": v.package,
+            "env_prefix": v.env_prefix,
+            "class_name": v.class_name,
+            "manage_url": v.manage_url,
+            "fields": [
+                {
+                    "name": f.name,
+                    "env_var": f.env_var,
+                    "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,
+                    "env_readable": f.env_readable,
+                    "db_override": f.db_override,
+                    "source": f.source,
+                    # Turns a pattern-constrained string into a select rather
+                    # than a text box whose only feedback on a typo is a 422.
+                    "choices": f.choices,
+                }
+                for f in v.fields
+            ],
+        }
+        for v in views
+    ]

simple_module_settings-0.0.34/settings/_row_masking.py

@@ -0,0 +1,68 @@
+"""Whether a stored row's value may be shown, and how the mask is honoured.
+
+Split out of ``service`` so the "is this a secret, and is this write the mask
+being echoed back?" question lives in one file, next to the field-level rules in
+``_secrets`` that it delegates to. ``service`` imports these; nothing else
+should need to, because the point of funnelling every read through ``out`` is
+that there is no second way to serialize a row.
+"""
+
+from __future__ import annotations
+
+from settings._secrets import conceals_secret
+from settings.constants import SENSITIVE_KEYS, SENSITIVE_PLACEHOLDER
+from settings.contracts.schemas import SettingOut
+from settings.models import Setting
+
+
+def is_masked(entity: Setting) -> bool:
+    """Whether this row's stored value must not leave the service.
+
+    :data:`SENSITIVE_KEYS` names the one key the hosting layer owns
+    (``host.secret_key``). Everything else is judged by the same name/value
+    rule the module editor uses, because the store is the *same data* seen
+    through a different screen: an override named ``users.smtp_password``, or
+    any override holding a ``postgresql://user:pw@host/db``, was rendered in
+    clear text in the browse table and pre-filled into the edit form purely
+    because the allowlist had a single entry in it.
+    """
+    return entity.key in SENSITIVE_KEYS or conceals_secret(
+        entity.key, entity.value, entity.value_type
+    )
+
+
+def out(entity: Setting) -> SettingOut:
+    """Serialize a row, masking values that must not leave the service.
+
+    Every read path funnels through here so a secret cannot be read back by
+    listing it, resolving it, or fetching it by id.
+    """
+    out = SettingOut.model_validate(entity)
+    if is_masked(entity):
+        return out.model_copy(update={"value": SENSITIVE_PLACEHOLDER})
+    return out
+
+
+def is_placeholder_write(entity: Setting, value: object) -> bool:
+    """Whether this write is the mask being echoed back, not a real new value.
+
+    The admin edit form GETs the row, pre-fills its input from the response,
+    and PUTs it back. For a masked row that response carries ``"********"``, so
+    an admin who opens the row and clicks Save — without touching the field —
+    would otherwise overwrite a real credential with a fixed, publicly-known
+    string. On ``host.secret_key`` that silently invalidates every session and
+    makes every future cookie forgeable.
+
+    Gated on the stored row rather than on the sentinel alone, so a non-secret
+    row whose real value happens to be eight asterisks still saves.
+
+    Treated as "leave it alone" rather than rejected, so the rest of the form
+    still saves and an admin who genuinely types a new value can still set one.
+    """
+    return is_masked(entity) and value == SENSITIVE_PLACEHOLDER
+
+
+def drop_placeholder_write(entity: Setting, changes: dict) -> None:
+    """Strip a masked-value echo out of an update payload, in place."""
+    if "value" in changes and is_placeholder_write(entity, changes["value"]):
+        del changes["value"]

simple_module_settings-0.0.34/settings/_secrets.py

@@ -0,0 +1,97 @@
+"""What counts as a secret on a settings field, and how one is hidden.
+
+Split out of ``_module_settings`` so the "should this value be shown?"
+question — a name rule, a value rule and one mask — lives in one file and can
+be reasoned about without a FastAPI app in scope. Re-exported from
+``_module_settings``, which is where the rest of the codebase imports it from.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+# We intentionally DON'T match the bare word "token" (would mask
+# `verification_token_lifetime_seconds` — just an int) or "key" alone (would
+# mask `s3_bucket_key_prefix`). Only fragments that actually indicate material.
+_SECRET_PATTERNS = re.compile(
+    r"(password|secret|api[_-]?key|private[_-]?key|token[_-]?secret)", re.I
+)
+SECRET_MASK = "••••••••"
+
+# Value types that cannot carry credential material, so a secret-ish *name*
+# on one of them is a false positive rather than something to hide.
+_NEVER_SECRET_TYPES = frozenset({"int", "float", "bool"})
+
+
+def is_secret_field(name: str) -> bool:
+    """True if a field name suggests it holds credential material."""
+    return bool(_SECRET_PATTERNS.search(name))
+
+
+def is_named_secret(name: str, value_type: str | None = None) -> bool:
+    """True if the *name* marks this field as credential material.
+
+    ``value_type`` exempts the types that cannot hold one, so a numeric field
+    whose name merely contains a secret-ish word is not masked and made
+    uneditable — ``reset_password_token_lifetime_seconds`` is an int, but it
+    matches on "password" exactly as the real secrets do. Phrased as "exempt
+    the types that cannot hold a credential" rather than "mask only strings" so
+    the failure direction is safe: an unexpected type (``str | None`` resolves
+    to "json") stays masked instead of silently exposing a secret.
+    """
+    if value_type in _NEVER_SECRET_TYPES:
+        return False
+    return is_secret_field(name)
+
+
+def conceals_secret(name: str, value: Any, value_type: str | None = None) -> bool:
+    """True if this name/value pair must be masked on the way out.
+
+    The one rule every read path shares: mask per *value* as well as per name,
+    so a DSN carrying a password is hidden even on a field called
+    ``broker_url``, while that field's password-free default is still shown.
+    """
+    return is_named_secret(name, value_type) or embeds_credential(value)
+
+
+def embeds_credential(value: Any) -> bool:
+    """True if ``value`` carries a password in a URL authority.
+
+    The name rule alone cannot see these: ``broker_url``, ``result_backend``,
+    ``redis_url`` and ``database_url`` match nothing in
+    :data:`_SECRET_PATTERNS`, yet a production DSN is precisely where the
+    Redis and Postgres passwords live — and those fields are ``env_readable``,
+    so the value reached both the module editor and the ``known_keys``
+    suggestion list in clear text.
+
+    Judged on the value rather than the name because the name is the thing
+    that was wrong. A DSN without a password stays visible: hiding
+    ``redis://localhost:6379/0`` helps nobody debug why the queue is idle.
+
+    Containers are walked rather than dismissed: a ``list[str]`` of broker
+    URLs or a ``dict`` of per-tenant DSNs holds exactly the same material as
+    the bare string, and returning False for anything non-``str`` meant one
+    such field would have been shown in full.
+    """
+    if isinstance(value, str):
+        if "://" not in value:
+            return False
+        try:
+            return bool(urlsplit(value).password)
+        except ValueError:
+            # A malformed authority (an unclosed IPv6 literal, say) is not a
+            # credential, but it must not take the settings screen down either.
+            return False
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return any(embeds_credential(item) for item in value)
+    if isinstance(value, dict):
+        return any(embeds_credential(item) for item in value.values())
+    return False
+
+
+def mask(value: Any) -> Any:
+    if value in (None, "", [], {}):
+        return value
+    return SECRET_MASK