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

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

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

{simple_module_settings-0.0.32 → simple_module_settings-0.0.33}/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.33}/pyproject.toml

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

simple_module_settings-0.0.33/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.33}/settings/_module_settings.py

@@ -7,31 +7,26 @@ 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,
+    embeds_credential,
+    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 +53,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 +95,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 +119,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 +128,52 @@ 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)
+    # A numeric field whose name merely contains a secret-ish word was being
+    # 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
+    # (e.g. `str | None`, which resolves to "json") stays masked instead of
+    # silently exposing a secret.
+    named_secret = value_type not in _NEVER_SECRET_TYPES and is_secret_field(name)
     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:
+        """Mask per *value*, not just per name: a DSN carrying a password is a
+        secret even on a field called ``broker_url``, while the same field's
+        password-free default is still worth showing."""
+        return named_secret or embeds_credential(value)
+
+    # ``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 +195,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 +218,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 +232,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 +245,7 @@ def _build_view(
         env_prefix=prefix,
         class_name=type(settings).__name__,
         fields=fields,
+        manage_url=manage_url,
     )
 
 
@@ -249,41 +260,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.33/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.33/settings/_secrets.py

@@ -0,0 +1,60 @@
+"""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 embeds_credential(value: Any) -> bool:
+    """True if ``value`` is a URL carrying a password in its 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.
+    """
+    if not isinstance(value, str) or "://" 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
+
+
+def mask(value: Any) -> Any:
+    if value in (None, "", [], {}):
+        return value
+    return SECRET_MASK

simple_module_settings-0.0.33/settings/browse_query.py

@@ -0,0 +1,49 @@
+"""Turn the store screen's query string into filters the service can run.
+
+Every parameter here arrives from a url an admin may have typed, bookmarked or
+kept open while the data moved underneath it. None of those are client errors
+worth a 422 page — a broken link should still render the table — so each one
+falls back to a sane value rather than rejecting the request. Clamping lives
+here rather than in the view so the ``filters``/``pagination`` props can echo
+exactly what the query ran with.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from settings.constants import ALL_SCOPES, DEFAULT_PER_PAGE, MAX_PER_PAGE, SCOPE_ALL
+from settings.contracts.schemas import SettingScope
+
+
+@dataclass(frozen=True, slots=True)
+class BrowseQuery:
+    """Validated, clamped filters for one render of the raw store."""
+
+    scope: str
+    """A tab value: ``all`` or one of the real scopes."""
+    q: str
+    page: int
+    per_page: int
+
+    @property
+    def scope_filter(self) -> SettingScope | None:
+        """The scope to filter on, or ``None`` for the ``all`` tab."""
+        return None if self.scope == SCOPE_ALL else SettingScope(self.scope)
+
+
+def _int_or(raw: str, fallback: int) -> int:
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def parse(scope: str, q: str, page: str, per_page: str) -> BrowseQuery:
+    """Read the four query params, substituting defaults for anything unusable."""
+    return BrowseQuery(
+        scope=scope if scope in ALL_SCOPES else SCOPE_ALL,
+        q=q,
+        page=max(_int_or(page, 1), 1),
+        per_page=max(1, min(_int_or(per_page, DEFAULT_PER_PAGE), MAX_PER_PAGE)),
+    )

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

@@ -42,9 +42,19 @@ ALL_VALUE_TYPES: Final = (
     VALUE_TYPE_JSON,
 )
 
+# ── Secrets ──────────────────────────────────────────────────────────
+# Keys whose stored value must never leave the settings API or the raw
+# key/value browse screen. ``host.secret_key`` is the session-signing key: the
+# hosting layer generates and persists it here when SM_SECRET_KEY is unset, and
+# anyone who can read it can forge a session cookie for any account. Masked on
+# the way out only — the boot-time reader goes straight to SQL, so hiding it
+# here costs nothing.
+SENSITIVE_KEYS: Final = frozenset({"host.secret_key"})
+SENSITIVE_PLACEHOLDER: Final = "********"
+
 # ── Routing ──────────────────────────────────────────────────────────
 API_PREFIX: Final = "/api/settings"
-VIEW_PREFIX: Final = "/settings"
+VIEW_PREFIX: Final = "/admin/settings"
 VIEW_CREATE_PATH: Final = "/create"
 VIEW_EDIT_PATH: Final = "/{setting_id}/edit"
 VIEW_MODULES_PATH: Final = "/modules"
@@ -101,6 +111,21 @@ PROP_SETTINGS: Final = "settings"
 PROP_SETTING: Final = "setting"
 PROP_MODULES: Final = "modules"
 PROP_ERROR: Final = "error"
+PROP_PAGINATION: Final = "pagination"
+PROP_COUNTS: Final = "counts"
+PROP_FILTERS: Final = "filters"
+PROP_KNOWN_KEYS: Final = "known_keys"
+PROP_TESTABLE: Final = "testable"
+
+# ── Store listing (scope tabs + search + paging) ─────────────────────
+# The table is server-filtered: the scope tabs report counts the client can no
+# longer compute once it holds a single page, and an install with a few
+# thousand overrides must not ship all of them to render twenty.
+SCOPE_ALL: Final = "all"
+"""Sentinel for "no scope filter" — a tab value, never a stored scope."""
+
+DEFAULT_PER_PAGE: Final = 20
+MAX_PER_PAGE: Final = 200
 
 # ── User-facing error messages ───────────────────────────────────────
 ERR_SETTING_NOT_FOUND: Final = "Setting not found"
@@ -121,3 +146,6 @@ QP_USER_ID: Final = "user_id"
 QP_TENANT_ID: Final = "tenant_id"
 QP_SCOPE: Final = "scope"
 QP_SCOPE_ID: Final = "scope_id"
+QP_Q: Final = "q"
+QP_PAGE: Final = "page"
+QP_PER_PAGE: Final = "per_page"