pypomes-jwt 1.2.3__py3-none-any.whl → 1.2.5__py3-none-any.whl

pypomes_jwt/__init__.py

@@ -1,5 +1,8 @@
 from .jwt_config import (
-    JwtConfig, JwtDbConfig
+    JwtConfig, JwtDbConfig, JwtAlgorithm
+)
+from .jwt_external import (
+    provider_register, provider_get_token
 )
 from .jwt_pomes import (
     jwt_needed, jwt_verify_request,
@@ -10,7 +13,9 @@ from .jwt_pomes import (
 
 __all__ = [
     # jwt_constants
-    "JwtConfig", "JwtDbConfig",
+    "JwtConfig", "JwtDbConfig", "JwtAlgorithm",
+    # jwt_external
+    "provider_register", "provider_get_token",
     # jwt_pomes
     "jwt_needed", "jwt_verify_request",
     "jwt_assert_account", "jwt_set_account", "jwt_remove_account",

pypomes_jwt/jwt_config.py

@@ -4,19 +4,29 @@ from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPubl
 from enum import Enum, StrEnum
 from pypomes_core import (
     APP_PREFIX,
-    env_get_str, env_get_bytes, env_get_int
+    env_get_str, env_get_bytes, env_get_int, env_get_enum
 )
 from secrets import token_bytes
 
 
+class JwtAlgorithm(StrEnum):
+    """
+    Supported decoding algorithms.
+    """
+    HS256 = "HS256"
+    HS512 = "HS512"
+    RS256 = "RS256"
+    RS512 = "RS512"
+
+
 # recommended: allow the encode and decode keys to be generated anew when app starts
 _encoding_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_ENCODING_KEY",
                                      encoding="base64url")
 _decoding_key: bytes
-# one of HS256, HS512, RS256, RS512
-_default_algorithm: str = env_get_str(key=f"{APP_PREFIX}_JWT_DEFAULT_ALGORITHM",
-                                      def_value="RS256")
-if _default_algorithm in ["HS256", "HS512"]:
+_default_algorithm: JwtAlgorithm = env_get_enum(key=f"{APP_PREFIX}_JWT_DEFAULT_ALGORITHM",
+                                                enum_class=JwtAlgorithm,
+                                                def_value=JwtAlgorithm.RS256)
+if _default_algorithm in [JwtAlgorithm.HS256, JwtAlgorithm.HS512]:
     if not _encoding_key:
         _encoding_key = token_bytes(nbytes=32)
     _decoding_key = _encoding_key
@@ -52,12 +62,12 @@ class JwtConfig(Enum):
 
 class JwtDbConfig(StrEnum):
     """
-    Parameters for JWT databse connection.
+    Parameters for JWT database connection.
     """
-    ENGINE: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_ENGINE")
-    TABLE: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_TABLE")
-    COL_ACCOUNT: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ACCOUNT")
-    COL_ALGORITHM: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ALGORITHM")
-    COL_DECODER: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_DECODER")
-    COL_KID: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_KID")
-    COL_TOKEN: str = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_TOKEN")
+    ENGINE = env_get_str(key=f"{APP_PREFIX}_JWT_DB_ENGINE")
+    TABLE = env_get_str(key=f"{APP_PREFIX}_JWT_DB_TABLE")
+    COL_ACCOUNT = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ACCOUNT")
+    COL_ALGORITHM = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ALGORITHM")
+    COL_DECODER = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_DECODER")
+    COL_KID = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_KID")
+    COL_TOKEN = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_TOKEN")

pypomes_jwt/jwt_external.py

@@ -0,0 +1,129 @@
+import requests
+import sys
+from base64 import b64encode
+from datetime import datetime
+from logging import Logger
+from pypomes_core import TZ_LOCAL, Mimetype, exc_format
+from requests import Response
+from typing import Any
+
+# structure:
+# {
+#    <provider-id>: {
+#      "url": <access-url>,
+#      "grant-type": <type-of-grant-to-request>,
+#      "user": <basic-auth-user>,
+#      "pwd": <basic-auth-pwd>,
+#      "client-id": <client-identification>,
+#      "use-header": <bool>,
+#      "token": <auth-token>,
+#      "expiration": <timestamp>
+#    }
+# }
+_provider_registry: dict[str, dict[str, Any]] = {}
+
+
+def provider_register(provider_id: str,
+                      access_url: str,
+                      grant_type: str,
+                      auth_user: str,
+                      auth_pwd: str,
+                      client_id: str = None,
+                      use_header: bool = None) -> None:
+    """
+    Register an external authentication token provider.
+
+    :param provider_id: the provider's identification
+    :param grant_type: the type of grant to request (typically, 'client_credentials' or 'password')
+    :param access_url: the url to request authentication tokens with
+    :param auth_user: the basic authorization user
+    :param auth_pwd: the basic authorization password
+    :param client_id: optional client identification to add to the request data
+    :param use_header: add authorization data to HTTP header (defaults to sending them in the body of the request)
+    """
+    global _provider_registry  # noqa: PLW0602
+    _provider_registry[provider_id] = {
+        "url": access_url,
+        "grant_type": grant_type,
+        "user": auth_user,
+        "pwd": auth_pwd,
+        "client-id": client_id,
+        "use-header": use_header,
+        "token": None,
+        "expiration": datetime.now(tz=TZ_LOCAL).timestamp()
+    }
+
+
+def provider_get_token(errors: list[str] | None,
+                       provider_id: str,
+                       logger: Logger = None) -> str | None:
+    """
+    Obtain an authentication token from the external provider *provider_id*.
+
+    :param errors: incidental error messages
+    :param provider_id: the provider's identification
+    :param logger: optional logger
+    """
+    # initialize the return variable
+    result: str | None = None
+
+    global _provider_registry  # noqa: PLW0602
+    err_msg: str | None = None
+    provider: dict[str, Any] = _provider_registry.get(provider_id)
+    if provider:
+        now: float = datetime.now(tz=TZ_LOCAL).timestamp()
+        if now > provider.get("expiration"):
+            user: str = provider.get("user")
+            pwd: str = provider.get("pwd")
+            data: dict[str, str] = {"grant-type": provider.get("grant-type")}
+            headers: dict[str, str] = {"Content-Type": Mimetype.URLENCODED}
+            if provider.get("use-header"):
+                enc_bytes: bytes = b64encode(f"{user}:{pwd}".encode())
+                headers["Authorization"] = f"Basic {enc_bytes.decode()}"
+            else:
+                data["username"] = user
+                data["password"] = pwd
+            if provider.get("client-id"):
+                data["client-id"] = provider.get("client-id")
+            url: str = provider.get("url")
+            try:
+                # typical return on a token request:
+                # {
+                #   "expires_in": <number-of-seconds>,
+                #   "token_type": "bearer",
+                #   "access_token": <the-token>
+                # }
+                response: Response = requests.post(url=url,
+                                                   data=data,
+                                                   headers=headers,
+                                                   timeout=None)
+                if response.status_code < 200 or response.status_code >= 300:
+                    # request resulted in error, report the problem
+                    err_msg = (f"POST '{url}': failed, "
+                               f"status {response.status_code}, reason '{response.reason}'")
+                else:
+                    reply: dict[str, Any] = response.json()
+                    provider["token"] = reply.get("access_token")
+                    provider["expiration"] = now + int(reply.get("expires_in"))
+                    if logger:
+                        logger.debug(msg=f"POST '{url}': status "
+                                         f"{response.status_code}, reason '{response.reason}')")
+            except Exception as e:
+                # the operation raised an exception
+                err_msg = exc_format(exc=e,
+                                     exc_info=sys.exc_info())
+                err_msg = f"POST '{url}': error, '{err_msg}'"
+    else:
+        err_msg: str = f"Provider '{provider_id}' not registered"
+
+    if err_msg:
+        if isinstance(errors, list):
+            errors.append(err_msg)
+        if logger:
+            logger.error(msg=err_msg)
+    else:
+        result = provider.get("token")
+
+    return result
+
+

pypomes_jwt/jwt_pomes.py

@@ -135,7 +135,7 @@ def jwt_validate_token(errors: list[str] | None,
                        account_id: str = None,
                        logger: Logger = None) -> dict[str, Any] | None:
     """
-    Verify if *token* ia a valid JWT token.
+    Verify if *token* is a valid JWT token.
 
     Attempt to validate non locally issued tokens will not succeed. If *nature* is provided,
     validate whether *token* is of that nature. A token issued locally has the header claim *kid*
@@ -152,7 +152,7 @@ def jwt_validate_token(errors: list[str] | None,
     :param nature: prefix identifying the nature of locally issued tokens
     :param account_id: optionally, validate the token's account owner
     :param logger: optional logger
-    :return: The token's claims (*header* and *payload*) if is valid, *None* otherwise
+    :return: The token's claims (*header* and *payload*) if it is valid, *None* otherwise
     """
     # initialize the return variable
     result: dict[str, Any] | None = None
@@ -516,7 +516,7 @@ def jwt_get_claims(errors: list[str] | None,
                    token: str,
                    logger: Logger = None) -> dict[str, Any] | None:
     """
-    Retrieve and return the claims set of a JWT *token*.
+    Retrieve the claims set of a JWT *token*.
 
     Any well-constructed JWT token may be provided in *token*, as this operation is not restricted
     to locally issued tokens. Note that neither the token's signature nor its expiration is verified.

{pypomes_jwt-1.2.3.dist-info → pypomes_jwt-1.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 1.2.3
+Version: 1.2.5
 Summary: A collection of Python pomes, penyeach (JWT module)
 Project-URL: Homepage, https://github.com/TheWiseCoder/PyPomes-JWT
 Project-URL: Bug Tracker, https://github.com/TheWiseCoder/PyPomes-JWT/issues
@@ -10,8 +10,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
-Requires-Dist: cryptography>=45.0.4
+Requires-Dist: cryptography>=45.0.6
 Requires-Dist: flask>=3.1.1
 Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: pypomes-core>=2.4.1
-Requires-Dist: pypomes-db>=2.2.9
+Requires-Dist: pypomes-core>=2.6.5
+Requires-Dist: pypomes-db>=2.4.8

pypomes_jwt-1.2.5.dist-info/RECORD

@@ -0,0 +1,9 @@
+pypomes_jwt/__init__.py,sha256=XS646zYwxnTHHfqnl5ioRN3YGi5QvIpKfrMZcw-grjM,966
+pypomes_jwt/jwt_config.py,sha256=3r9XPWXXAG_wKUs_FDZoTj9j6lmTdNymud_q4E4Opk0,3338
+pypomes_jwt/jwt_external.py,sha256=tEMsOO3Q-rbWR-6TR_7yapB7Xe9qDVvrL-h8RbxgB2I,5145
+pypomes_jwt/jwt_pomes.py,sha256=em_apYg0ptfa5BvobnfXz7BPh_ghPhXGg7zHFK3A8y4,23901
+pypomes_jwt/jwt_registry.py,sha256=pNBpPiR2xINzNnWu_2dcPtRVfXqqPzMVYCXG1HtatUA,22268
+pypomes_jwt-1.2.5.dist-info/METADATA,sha256=Ib7ZJwqF9ZzIENLC27xxddSw-_oPIlnDnftKEVxvs6c,660
+pypomes_jwt-1.2.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pypomes_jwt-1.2.5.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
+pypomes_jwt-1.2.5.dist-info/RECORD,,

pypomes_jwt-1.2.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-pypomes_jwt/__init__.py,sha256=NZzjWKnhjxNuoE32V6soKo9sG5ypmt25V0mBAh3rAIs,793
-pypomes_jwt/jwt_config.py,sha256=mtihd58_O00FuFXcNBKsabftG6UHu3Cj24i6cZXoskc,3096
-pypomes_jwt/jwt_pomes.py,sha256=pFqorpjBlnsafn2Ptc-r3z61QZhgaRKbmWKaBsWmq9U,23909
-pypomes_jwt/jwt_registry.py,sha256=pNBpPiR2xINzNnWu_2dcPtRVfXqqPzMVYCXG1HtatUA,22268
-pypomes_jwt-1.2.3.dist-info/METADATA,sha256=MERUHKMpNm5SI1NjYzfY8eB9GEYJsWYa6mwsQSDgySM,660
-pypomes_jwt-1.2.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pypomes_jwt-1.2.3.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
-pypomes_jwt-1.2.3.dist-info/RECORD,,