kstlib 2.7.0__tar.gz → 3.0.0__tar.gz

{kstlib-2.7.0/src/kstlib.egg-info → kstlib-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kstlib
-Version: 2.7.0
+Version: 3.0.0
 Summary: Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)
 Author-email: Michel TRUONG <michel.truong@gmail.com>
 Maintainer-email: Michel TRUONG <michel.truong@gmail.com>
@@ -42,11 +42,12 @@ Requires-Dist: websockets<16,>=15.0
 Requires-Dist: jinja2<4,>=3.1.5
 Requires-Dist: humanize<5,>=4.11
 Requires-Dist: httpx<1,>=0.28
-Requires-Dist: authlib<2,>=1.6.11
+Requires-Dist: authlib<2,>=1.6.12
 Requires-Dist: pendulum<4,>=3.0
 Requires-Dist: cryptography>=46.0.7
+Requires-Dist: idna>=3.15
 Requires-Dist: requests>=2.33.0
-Requires-Dist: urllib3>=2.6.3
+Requires-Dist: urllib3>=2.7.0
 Provides-Extra: dev
 Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
 Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"

{kstlib-2.7.0 → kstlib-3.0.0}/pyproject.toml

@@ -56,15 +56,16 @@ dependencies = [
 
     # --- HTTP Client & Auth ---
     "httpx>=0.28,<1",  # Modern async HTTP client (OAuth2/OIDC flows)
-    "authlib>=1.6.11,<2", # OAuth2/OIDC client + JWT signature verification (GHSA-jj8c-mmj3-mmgv: CSRF in cache-backed OAuth state)
+    "authlib>=1.6.12,<2", # OAuth2/OIDC client + JWT signature verification (>=1.6.12 open-redirect fix; GHSA-jj8c-mmj3-mmgv CSRF)
 
     # --- Time & Scheduling ---
     "pendulum>=3.0,<4", # Modern datetime library with timezone support
 
     # --- Security: transitive dep lower bounds (CVE) ---
     "cryptography>=46.0.7",  # CVE-2026-26007 + CVE-2026-34073 + CVE-2026-39892
+    "idna>=3.15",            # CVE-2026-45409 (DoS quadratic-time, bypass of CVE-2024-3651 mitigation; via httpx)
     "requests>=2.33.0",      # CVE-2024-47081 + CVE-2026-25645 (via httpx)
-    "urllib3>=2.6.3",         # CVE-2025-50182/50181 + CVE-2025-66418/66471 + CVE-2026-21441 (via requests)
+    "urllib3>=2.7.0",         # CVE-2025-50182/50181 + CVE-2025-66418/66471 + CVE-2026-21441 + CVE-2026-44431 + CVE-2026-44432 (via requests)
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -573,4 +574,5 @@ exclude_lines = [
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
     "@abstractmethod",
+    "^\\s*\\.\\.\\.\\s*$",
 ]

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/auth/__init__.py

@@ -58,6 +58,7 @@ from kstlib.auth.config import (
 )
 from kstlib.auth.errors import (
     AuthError,
+    AuthExpiredError,
     AuthorizationError,
     CallbackServerError,
     ConfigurationError,
@@ -100,6 +101,7 @@ __all__ = [
     "AbstractTokenStorage",
     # Errors
     "AuthError",
+    "AuthExpiredError",
     # Models
     "AuthFlow",
     "AuthProviderConfig",

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/auth/errors.py

@@ -119,8 +119,89 @@ class PreflightError(AuthError):
         self.reason = reason
 
 
+class AuthExpiredError(AuthError):
+    """Raised when an authenticated request returns HTTP 401 indicating token expiration.
+
+    Surfaced by ``kstlib.rapi.client`` (and any other consumer) when a
+    server response signals that the previously-valid access token has
+    expired or been invalidated during the session. The user must
+    re-authenticate via the appropriate channel (for example,
+    ``sas-admin auth login`` for Viya, or via a dedicated OAuth client
+    when configured in :mod:`kstlib.auth`).
+
+    Note:
+        Distinct from :class:`TokenExpiredError`. The two cover
+        different lifecycle points and originate from different
+        sub-systems :
+
+        - ``AuthExpiredError`` (this class, inherits from
+          :class:`AuthError`) is raised by ``kstlib.rapi.client`` when
+          the server returns HTTP 401 at runtime, signalling that a
+          token which was valid at send time has been expired or
+          invalidated by the identity provider during the session.
+
+        - :class:`TokenExpiredError` (inherits from :class:`TokenError`)
+          is raised by ``kstlib.auth`` when a loaded token is detected
+          as already expired before the request is sent (client-side
+          pre-flight check).
+
+    Attributes:
+        token_source: Optional label identifying where the token was
+            loaded from (for example, ``'~/.sas/credentials.json'``,
+            ``'env:KSTLIB_TOKEN'``, ``'sops:secrets/api.sops.json'``).
+            ``None`` when the source is unknown.
+        suggested_action: Optional human-readable hint guiding the
+            user toward a successful re-authentication (for example,
+            ``'Run: sas-admin auth login -u <user>'``). ``None`` when
+            no contextual hint is available.
+
+    Examples:
+        >>> err = AuthExpiredError(
+        ...     "Access token expired (HTTP 401).",
+        ...     token_source="~/.sas/credentials.json",
+        ...     suggested_action="Run: sas-admin auth login -u <user>",
+        ... )
+        >>> err.token_source
+        '~/.sas/credentials.json'
+        >>> isinstance(err, AuthError)
+        True
+
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        token_source: str | None = None,
+        suggested_action: str | None = None,
+    ) -> None:
+        """Initialize AuthExpiredError.
+
+        Args:
+            message: Human-readable description of the expiration
+                (typically including the HTTP status and a short
+                rationale, never the raw token or response body).
+            token_source: Optional label for where the token came from
+                (used by callers to surface a contextual hint without
+                exposing the secret material itself).
+            suggested_action: Optional hint pointing the user to the
+                right re-authentication procedure.
+
+        """
+        super().__init__(
+            message,
+            details={
+                "token_source": token_source,
+                "suggested_action": suggested_action,
+            },
+        )
+        self.token_source = token_source
+        self.suggested_action = suggested_action
+
+
 __all__ = [
     "AuthError",
+    "AuthExpiredError",
     "AuthorizationError",
     "CallbackServerError",
     "ConfigurationError",

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/cli/commands/rapi/call.py

@@ -7,6 +7,7 @@ from typing import Annotated, Any, cast
 
 import typer
 
+from kstlib.auth import AuthExpiredError
 from kstlib.cli.common import CommandResult, CommandStatus, console, exit_error, exit_with_result
 from kstlib.limits import get_rapi_render_config
 from kstlib.rapi import (
@@ -119,6 +120,96 @@ def _parse_body(body: str | None) -> dict[str, Any] | list[Any] | None:
         exit_error(f"Invalid JSON body: {e}")
 
 
+def _validate_format(fmt: str) -> None:
+    """Reject output formats outside the supported set with a friendly error.
+
+    Extracted from the ``call`` command body so the cyclomatic
+    complexity budget keeps room for the exception handlers that
+    cover the runtime error paths (auth expiration, HTTP errors,
+    safeguard checks, etc.).
+
+    Args:
+        fmt: Format value passed by the user via ``--format`` / ``-f``.
+
+    Raises:
+        typer.Exit: Exit code 1 if ``fmt`` is not one of ``json``,
+            ``text``, or ``full``.
+
+    """
+    if fmt not in ("json", "text", "full"):
+        exit_error(f"Invalid output format: '{fmt}'\nValid formats: json, text, full")
+
+
+def _is_multipart_file_body(endpoint_config: Any, body: str | None) -> bool:
+    """Return True when the call targets a multipart endpoint with a ``@file`` body.
+
+    Extracted from the ``call`` command body to keep its cyclomatic
+    complexity in check. The compound check is pulled out so each
+    short-circuit (``and``) does not count as a separate branch
+    against the caller's complexity budget.
+    """
+    return endpoint_config.is_multipart and body is not None and body.startswith("@")
+
+
+def _handle_auth_expired_error(error: AuthExpiredError, *, quiet: bool) -> None:
+    """Render an :class:`AuthExpiredError` and exit with code 4.
+
+    Distinct exit code lets shell scripts detect token expiration
+    specifically and trigger an automated re-login flow (decision
+    D5 in the v3.0.0 roadmap). The message body is built from the
+    exception attributes : ``Error: <message>``, optionally
+    ``Source: <token_source>``, optionally ``Hint: <suggested_action>``.
+
+    Args:
+        error: The caught :class:`AuthExpiredError`.
+        quiet: Whether the user passed ``--quiet`` / ``-q``.
+
+    Raises:
+        typer.Exit: Always exits with code 4.
+
+    """
+    message_lines = [f"Error: {error.message}"]
+    if error.token_source:
+        message_lines.append(f"Source: {error.token_source}")
+    if error.suggested_action:
+        message_lines.append(f"Hint: {error.suggested_action}")
+    exit_with_result(
+        CommandResult(
+            status=CommandStatus.ERROR,
+            message="\n".join(message_lines),
+            payload={
+                "token_source": error.token_source,
+                "suggested_action": error.suggested_action,
+            },
+        ),
+        quiet=quiet,
+        exit_code=4,
+        cause=error,
+    )
+
+
+def _validate_output_flags(raw: bool, minify: bool) -> None:
+    """Reject ``--minify`` without ``--raw`` at command entry.
+
+    Rich console rendering reformats output regardless of compact JSON
+    flags, so ``--minify`` without ``--raw`` is silently ineffective.
+    Fail fast with a hint instead of swallowing the user intent.
+
+    Args:
+        raw: True if the user passed ``--raw``.
+        minify: True if the user passed ``--minify``.
+
+    Raises:
+        typer.BadParameter: If ``minify`` is True and ``raw`` is False.
+            The message contains the hint ``--raw --minify``.
+
+    """
+    if minify and not raw:
+        raise typer.BadParameter(
+            "--minify requires --raw (Rich rendering ignores compact JSON formatting). Hint: use --raw --minify.",
+        )
+
+
 def _serialize_json(data: Any, *, minify: bool = False, indent: int = 2) -> str:
     """Serialize data to JSON string.
 
@@ -331,8 +422,10 @@ def call(
     headers = _parse_headers(header or [])
 
     # Validate output format
-    if fmt not in ("json", "text", "full"):
-        exit_error(f"Invalid output format: '{fmt}'\nValid formats: json, text, full")
+    _validate_format(fmt)
+
+    # Reject --minify without --raw before any work is done.
+    _validate_output_flags(raw=raw, minify=minify)
 
     from kstlib.cli.commands.rapi import _load_config_or_exit
 
@@ -346,7 +439,7 @@ def call(
 
         # For multipart endpoints with @file body, pass raw string to client
         # (client reads file as binary instead of CLI parsing as JSON)
-        if endpoint_config.is_multipart and body is not None and body.startswith("@"):
+        if _is_multipart_file_body(endpoint_config, body):
             parsed_body: Any = body
         else:
             parsed_body = _parse_body(body)
@@ -413,6 +506,8 @@ def call(
             exit_code=1,
             cause=e,
         )
+    except AuthExpiredError as e:
+        _handle_auth_expired_error(e, quiet=quiet)
     except RequestError as e:
         exit_with_result(
             CommandResult(

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/config/export.py

@@ -20,6 +20,7 @@ from typing import Any, Final, cast
 
 import yaml
 
+from kstlib.config.exceptions import ConfigError
 from kstlib.config.loader import CONFIG_FILENAME
 
 try:
@@ -38,7 +39,7 @@ _SUPPORTED_EXTENSIONS: Final[dict[str, str]] = {
 _DEFAULT_FORMAT: Final[str] = "yaml"
 
 
-class ConfigExportError(RuntimeError):
+class ConfigExportError(ConfigError, RuntimeError):
     """Raised when configuration export fails."""
 
 

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/kstlib.conf.yml

@@ -228,6 +228,7 @@ logger:
         tracebacks_show_locals: true
       file:
         level: TRACE
+        format: "[%(asctime)s | %(levelname)-8s] ::: PID %(process)d / TID %(thread)d ::: [%(filename)s:%(lineno)d %(funcName)s] %(message)s"
       icons:
         show: true
 
@@ -239,6 +240,7 @@ logger:
         tracebacks_show_locals: true
       file:
         level: TRACE
+        format: "[%(asctime)s | %(levelname)-8s] ::: PID %(process)d / TID %(thread)d ::: [%(filename)s:%(lineno)d %(funcName)s] %(message)s"
       icons:
         show: true
 

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/meta.py

@@ -39,7 +39,7 @@ __logo__ = (
 )
 
 __app_name__ = "kstlib"
-__version__ = "2.7.0"
+__version__ = "3.0.0"
 __description__ = (
     "Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)"
 )

{kstlib-2.7.0 → kstlib-3.0.0}/src/kstlib/rapi/__init__.py

@@ -97,6 +97,7 @@ from kstlib.rapi.exceptions import (
     EndpointAmbiguousError,
     EndpointNotFoundError,
     EnvVarError,
+    MinifyRequiresRawError,
     RapiError,
     RequestError,
     ResponseTooLargeError,
@@ -116,6 +117,7 @@ __all__ = [
     "EnvVarError",
     "FilePayload",
     "HmacConfig",
+    "MinifyRequiresRawError",
     "MultipartConfig",
     "RapiClient",
     "RapiConfigManager",