pypomes-jwt 0.5.6__tar.gz → 0.5.8__tar.gz

{pypomes_jwt-0.5.6 → pypomes_jwt-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.5.6
+Version: 0.5.8
 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

{pypomes_jwt-0.5.6 → pypomes_jwt-0.5.8}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_jwt"
-version = "0.5.6"
+version = "0.5.8"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]

{pypomes_jwt-0.5.6 → pypomes_jwt-0.5.8}/src/pypomes_jwt/jwt_data.py

@@ -36,8 +36,8 @@ class JwtData:
                "request-timeout": <float>,   # in seconds - defaults to no timeout
                "access-max-age": <int>,      # in seconds - defaults to JWT_ACCESS_MAX_AGE
                "refresh-exp": <timestamp>,   # expiration time for the refresh operation
-               "service-url": <url>,         # URL to obtain and validate the access tokens
-               "local-provider": <bool>,     # whether 'service-url' is a local endpoint
+               "reference-url": <url>,       # URL to obtain and validate the access tokens
+               "remote-provider": <bool>,    # whether the JWT provider is a remote server
                "secret-key": <bytes>,        # HS secret key
                "private-key": <bytes>,       # RSA private key
                "public-key": <bytes>,        # RSA public key
@@ -54,7 +54,7 @@ class JwtData:
         self.access_data: list[dict[str, dict[str, Any]]] = []
 
     def add_access_data(self,
-                        service_url: str,
+                        reference_url: str,
                         claims: dict[str, Any],
                         algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"],
                         access_max_age: int,
@@ -63,15 +63,16 @@ class JwtData:
                         private_key: bytes,
                         public_key: bytes,
                         request_timeout: float,
+                        remote_provider: bool,
                         logger: Logger = None) -> None:
         """
-        Add to storage the parameters needed to obtain and validate JWT tokens.
+        Add to storage the parameters needed to obtain and validate JWT tokens for *reference_url*.
 
         Presently, the *refresh_max_age* data is not relevant, as the authorization parameters in *claims*
         (typically, an acess-key/secret-key pair), have been previously validated elsewhere.
         This situation might change in the future.
 
-        :param service_url: the reference URL
+        :param reference_url: the reference URL
         :param claims: the JWT claimset, as key-value pairs
         :param algorithm: the algorithm used to sign the token with
         :param access_max_age: token duration
@@ -80,18 +81,18 @@ class JwtData:
         :param private_key: private key for RSA authentication
         :param public_key: public key for RSA authentication
         :param request_timeout: timeout for the requests to the service URL
+        :param remote_provider: whether the JWT provider is a remote server
         :param logger: optional logger
         """
-        # obtain the item in storage
-        item_data: dict[str, dict[str, Any]] = self.retrieve_access_data(service_url=service_url,
-                                                                         logger=logger)
-        if not item_data:
-            # build control data
+        # Do the access data already exist ?
+        if not self.assert_access_data(reference_url=reference_url):
+            # no, build control data
             control_data: dict[str, Any] = {
-                "service-url": service_url,
+                "reference-url": reference_url,
                 "algorithm": algorithm,
                 "access-max-age": access_max_age,
                 "request-timeout": request_timeout,
+                "remote-provider": remote_provider,
                 "refresh-exp": datetime.now(tz=timezone.utc) + timedelta(seconds=refresh_max_age)
             }
             if algorithm in ["HS256", "HS512"]:
@@ -121,35 +122,35 @@ class JwtData:
             with self.access_lock:
                 self.access_data.append(item_data)
             if logger:
-                logger.debug(f"JWT data added for '{service_url}': {item_data}")
+                logger.debug(f"JWT data added for '{reference_url}': {item_data}")
         elif logger:
-            logger.warning(f"JWT data already exists for '{service_url}'")
+            logger.warning(f"JWT data already exists for '{reference_url}'")
 
     def remove_access_data(self,
-                           service_url: str,
+                           reference_url: str,
                            logger: Logger) -> None:
         """
-        Remove from storage the access data associated with the given parameters.
+        Remove from storage the access data for *reference_url*.
 
-        :param service_url: the reference URL
+        :param reference_url: the reference URL
         :param logger: optional logger
         """
-        # obtain the item in storage
-        item_data: dict[str, dict[str, Any]] = self.retrieve_access_data(service_url=service_url,
+        # obtain the access data item in storage
+        item_data: dict[str, dict[str, Any]] = self.retrieve_access_data(reference_url=reference_url,
                                                                          logger=logger)
         if item_data:
             with self.access_lock:
                 self.access_data.remove(item_data)
             if logger:
-                logger.debug(f"Removed JWT data for '{service_url}'")
+                logger.debug(f"Removed JWT data for '{reference_url}'")
         elif logger:
-            logger.warning(f"No JWT data found for '{service_url}'")
+            logger.warning(f"No JWT data found for '{reference_url}'")
 
     def get_token_data(self,
-                       service_url: str,
+                       reference_url: str,
                        logger: Logger = None) -> dict[str, Any]:
         """
-        Obtain and return the JWT token associated with *service_url*, along with its duration.
+        Obtain and return the JWT token for *reference_url*, along with its duration.
 
         Structure of the return data:
         {
@@ -157,7 +158,7 @@ class JwtData:
           "expires_in": <seconds-to-expiration>
         }
 
-        :param service_url: the reference URL for obtaining JWT tokens
+        :param reference_url: the reference URL for obtaining JWT tokens
         :param logger: optional logger
         :return: the JWT token data, or 'None' if error
         :raises InvalidTokenError: token is invalid
@@ -170,14 +171,14 @@ class JwtData:
         :raises InvalidIssuerError: 'iss' claim does not match the expected issuer
         :raises InvalidIssuedAtError: 'iat' claim is non-numeric
         :raises MissingRequiredClaimError: a required claim is not contained in the claimset
-        :raises RuntimeError: access data not found for the given *service_url*, or
+        :raises RuntimeError: access data not found for the given *reference_url*, or
                               the remote JWT provider failed to return a token
         """
         # declare the return variable
         result: dict[str, Any]
 
         # obtain the item in storage
-        item_data: dict[str, Any] = self.retrieve_access_data(service_url=service_url,
+        item_data: dict[str, Any] = self.retrieve_access_data(reference_url=reference_url,
                                                               logger=logger)
         # was the JWT data obtained ?
         if item_data:
@@ -190,29 +191,19 @@ class JwtData:
             # is the current token still valid ?
             if just_now > standard_claims.get("exp"):
                 # no, obtain a new token
-                service_url: str = control_data.get("service-url")
+                reference_url: str = control_data.get("reference-url")
                 claims: dict[str, Any] = standard_claims.copy()
                 claims.update(custom_claims)
 
-                # where is the locus of the JWT service ?
-                if control_data.get("local-provider"):
-                    # JWT service is local
-                    claims["exp"] = just_now + timedelta(seconds=control_data.get("access-max-age") + 10)
-                    # may raise an exception
-                    token: str = jwt.encode(payload=claims,
-                                            key=control_data.get("secret-key") or control_data.get("private-key"),
-                                            algorithm=control_data.get("algorithm"))
-                    with self.access_lock:
-                        control_data["access-token"] = token
-                        standard_claims["exp"] = claims.get("exp")
-                else:
-                    # JWT service is remote
-                    if service_url.find("?") > 0:
-                        service_url = service_url[:service_url.index("?")]
+                # where is the locus of the JWT service provider ?
+                if control_data.get("remote-provider"):
+                    # JWT service is being provided by a remote server
+                    if reference_url.find("?") > 0:
+                        reference_url = reference_url[:reference_url.index("?")]
                     claims.pop("exp", None)
                     errors: list[str] = []
                     result = jwt_request_token(errors=errors,
-                                               service_url=service_url,
+                                               reference_url=reference_url,
                                                claims=claims,
                                                timeout=control_data.get("request-timeout"),
                                                logger=logger)
@@ -223,6 +214,16 @@ class JwtData:
                             standard_claims["exp"] = just_now + timedelta(seconds=duration)
                     else:
                         raise RuntimeError(" - ".join(errors))
+                else:
+                    # JWT service is being provided locally
+                    claims["exp"] = just_now + timedelta(seconds=control_data.get("access-max-age") + 10)
+                    # may raise an exception
+                    token: str = jwt.encode(payload=claims,
+                                            key=control_data.get("secret-key") or control_data.get("private-key"),
+                                            algorithm=control_data.get("algorithm"))
+                    with self.access_lock:
+                        control_data["access-token"] = token
+                        standard_claims["exp"] = claims.get("exp")
 
             # return the token
             diff: timedelta = standard_claims.get("exp") - just_now - timedelta(seconds=10)
@@ -231,8 +232,8 @@ class JwtData:
                 "expires_in": math.trunc(diff.total_seconds())
             }
         else:
-            # JWT data not found
-            err_msg: str = f"No JWT data found for {service_url}"
+            # JWT access data not found
+            err_msg: str = f"No JWT access data found for '{reference_url}'"
             if logger:
                 logger.error(err_msg)
             raise RuntimeError(err_msg)
@@ -274,49 +275,85 @@ class JwtData:
 
         return result
 
+    def assert_access_data(self,
+                           reference_url: str) -> bool:
+        # noinspection HttpUrlsUsage
+        """
+        Assert whether access data exists for *reference_url*.
+
+        For the purpose of locating access data, Protocol indication in *reference_url*
+        (typically, *http://* or *https://*), is disregarded. This guarantees
+        that processing herein will not be affected by in-transit protocol changes.
+
+        :param reference_url: the reference URL for obtaining JWT tokens
+        :return: *True" is access data is in storage, *False* otherwise
+        """
+        # initialize the return variable
+        result: bool = False
+
+        # disregard protocol
+        if reference_url.find("://") > 0:
+            reference_url = reference_url[reference_url.index("://")+3:]
+
+        # assert the data
+        with self.access_lock:
+            for item_data in self.access_data:
+                item_url: str = item_data.get("control-data").get("reference-url")
+                if item_url.find("://") > 0:
+                    item_url = item_url[item_url.index("://")+3:]
+                if reference_url == item_url:
+                    result = True
+                    break
+        
+        return result
+
     def retrieve_access_data(self,
-                             service_url: str,
+                             reference_url: str,
                              logger: Logger = None) -> dict[str, dict[str, Any]]:
         # noinspection HttpUrlsUsage
         """
-                Retrieve and return the access data in storage corresponding to *service_url*.
+        Retrieve and return the access data in storage for *reference_url*.
 
-                For the purpose of retrieving access data, Protocol indication in *service_url*
-                (typically, *http://* or *https://*), is disregarded. This guarantees
-                that processing herein will not be affected by in-transit protocol changes.
+        For the purpose of locating access data, Protocol indication in *reference_url*
+        (typically, *http://* or *https://*), is disregarded. This guarantees
+        that processing herein will not be affected by in-transit protocol changes.
 
-                :param service_url: the reference URL for obtaining JWT tokens
-                :param logger: optional logger
-                :return: the corresponding item in storage, or *None* if not found
-                """
+        :param reference_url: the reference URL for obtaining JWT tokens
+        :param logger: optional logger
+        :return: the corresponding item in storage, or *None* if not found
+        """
         # initialize the return variable
         result: dict[str, dict[str, Any]] | None = None
+    
+        if logger:
+            logger.debug(f"Retrieve access data for reference URL '{reference_url}'")
 
         # disregard protocol
-        if service_url.find("://") > 0:
-            service_url = service_url[service_url.index("://")+3:]
+        if reference_url.find("://") > 0:
+            reference_url = reference_url[reference_url.index("://")+3:]
 
+        # retrieve the data
         with self.access_lock:
             for item_data in self.access_data:
-                item_url: str = item_data.get("control-data").get("service-url")
+                item_url: str = item_data.get("control-data").get("reference-url")
                 if item_url.find("://") > 0:
                     item_url = item_url[item_url.index("://")+3:]
-                if service_url == item_url:
+                if reference_url == item_url:
                     result = item_data
                     break
         if logger:
-            logger.debug(f"JWT data for '{service_url}': {result}")
+            logger.debug(f"Data is '{result}'")
 
         return result
 
 
 def jwt_request_token(errors: list[str],
-                      service_url: str,
+                      reference_url: str,
                       claims: dict[str, Any],
                       timeout: float = None,
                       logger: Logger = None) -> dict[str, Any]:
     """
-    Obtain and return the JWT token associated with *service_url*, along with its duration.
+    Obtain and return the JWT token associated with *reference_url*, along with its duration.
 
     Expected structure of the return data:
     {
@@ -327,7 +364,7 @@ def jwt_request_token(errors: list[str],
     of the provider issuing the JWT token.
 
     :param errors: incidental errors
-    :param service_url: the reference URL for obtaining JWT tokens
+    :param reference_url: the reference URL for obtaining JWT tokens
     :param claims: the JWT claimset, as expected by the issuing server
     :param timeout: request timeout, in seconds (defaults to *None*)
     :param logger: optional logger
@@ -337,9 +374,9 @@ def jwt_request_token(errors: list[str],
 
     # request the JWT token
     if logger:
-        logger.debug(f"POST request JWT token to '{service_url}'")
+        logger.debug(f"POST request JWT token to '{reference_url}'")
     response: Response = requests.post(
-        url=service_url,
+        url=reference_url,
         json=claims,
         timeout=timeout
     )
@@ -352,7 +389,7 @@ def jwt_request_token(errors: list[str],
             logger.debug(f"JWT token obtained: {result}")
     else:
         # no, report the problem
-        err_msg: str = f"POST request of '{service_url}' failed: {response.reason}"
+        err_msg: str = f"POST request of '{reference_url}' failed: {response.reason}"
         if response.text:
             err_msg += f" - {response.text}"
         if logger:

{pypomes_jwt-0.5.6 → pypomes_jwt-0.5.8}/src/pypomes_jwt/jwt_pomes.py

@@ -16,7 +16,7 @@ JWT_REFRESH_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_REFRESH_MAX
                                               def_value=43200)
 JWT_HS_SECRET_KEY: Final[bytes] = env_get_bytes(key=f"{APP_PREFIX}_JWT_HS_SECRET_KEY",
                                                 def_value=token_bytes(32))
-# must point to 'jwt_service()' below
+# must invoke 'jwt_service()' below
 JWT_ENDPOINT_URL: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_ENDPOINT_URL")
 
 __priv_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PRIVATE_KEY")
@@ -49,7 +49,7 @@ def jwt_needed(func: callable) -> callable:
     return wrapper
 
 
-def jwt_set_service_access(service_url: str,
+def jwt_set_service_access(reference_url: str,
                            claims: dict[str, Any],
                            algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"] = JWT_DEFAULT_ALGORITHM,
                            access_max_age: int = JWT_ACCESS_MAX_AGE,
@@ -58,11 +58,12 @@ def jwt_set_service_access(service_url: str,
                            private_key: bytes = JWT_RSA_PRIVATE_KEY,
                            public_key: bytes = JWT_RSA_PUBLIC_KEY,
                            request_timeout: int = None,
+                           remote_provider: bool = True,
                            logger: Logger = None) -> None:
     """
-    Set the data needed to obtain JWT tokens from *service_url*.
+    Set the data needed to obtain JWT tokens from *reference_url*.
 
-    :param service_url: the reference URL
+    :param reference_url: the reference URL
     :param claims: the JWT claimset, as key-value pairs
     :param algorithm: the authentication type
     :param access_max_age: token duration, in seconds
@@ -71,18 +72,22 @@ def jwt_set_service_access(service_url: str,
     :param private_key: private key for RSA authentication
     :param public_key: public key for RSA authentication
     :param request_timeout: timeout for the requests to the service URL
+    :param remote_provider: whether the JWT provider is a remote server
     :param logger: optional logger
     """
+    if logger:
+        logger.debug(msg=f"Register access data for reference URL '{reference_url}'")
     # extract the extra claims
-    pos: int = service_url.find("?")
+    pos: int = reference_url.find("?")
     if pos > 0:
-        params: list[str] = service_url[pos+1:].split(sep="&")
-        for param in params:
-            claims[param.split("=")[0]] = param.split("=")[1]
-        service_url = service_url[:pos]
+        if remote_provider:
+            params: list[str] = reference_url[pos+1:].split(sep="&")
+            for param in params:
+                claims[param.split("=")[0]] = param.split("=")[1]
+        reference_url = reference_url[:pos]
 
     # register the JWT service
-    __jwt_data.add_access_data(service_url=service_url,
+    __jwt_data.add_access_data(reference_url=reference_url,
                                claims=claims,
                                algorithm=algorithm,
                                access_max_age=access_max_age,
@@ -91,39 +96,48 @@ def jwt_set_service_access(service_url: str,
                                private_key=private_key,
                                public_key=public_key,
                                request_timeout=request_timeout,
+                               remote_provider=remote_provider,
                                logger=logger)
 
 
-def jwt_remove_service_access(service_url: str,
+def jwt_remove_service_access(reference_url: str,
                               logger: Logger = None) -> None:
     """
-    Remove from storage the JWT access data for *service_url*.
+    Remove from storage the JWT access data for *reference_url*.
 
-    :param service_url: the reference URL
+    :param reference_url: the reference URL
     :param logger: optional logger
     """
-    __jwt_data.remove_access_data(service_url=service_url,
+    if logger:
+        logger.debug(msg=f"Remove access data for reference URL '{reference_url}'")
+
+    __jwt_data.remove_access_data(reference_url=reference_url,
                                   logger=logger)
 
 
 def jwt_get_token(errors: list[str],
-                  service_url: str,
+                  reference_url: str,
                   logger: Logger = None) -> str:
     """
-    Obtain and return a JWT token from *service_url*.
+    Obtain and return a JWT token from *reference_url*.
 
     :param errors: incidental error messages
-    :param service_url: the reference URL
+    :param reference_url: the reference URL
     :param logger: optional logger
     :return: the JWT token, or 'None' if an error ocurred
     """
     # inicialize the return variable
     result: str | None = None
 
+    if logger:
+        logger.debug(msg=f"Obtain a JWT token for reference URL '{reference_url}'")
+
     try:
-        token_data: dict[str, Any] = __jwt_data.get_token_data(service_url=service_url,
+        token_data: dict[str, Any] = __jwt_data.get_token_data(reference_url=reference_url,
                                                                logger=logger)
         result = token_data.get("access_token")
+        if logger:
+            logger.debug(f"Token is '{result}'")
     except Exception as e:
         if logger:
             logger.error(msg=str(e))
@@ -133,10 +147,10 @@ def jwt_get_token(errors: list[str],
 
 
 def jwt_get_token_data(errors: list[str],
-                       service_url: str,
+                       reference_url: str,
                        logger: Logger = None) -> dict[str, Any]:
     """
-    Obtain and return the JWT token associated with *service_url*, along with its duration.
+    Obtain and return the JWT token associated with *reference_url*, along with its duration.
 
     Structure of the return data:
     {
@@ -145,16 +159,20 @@ def jwt_get_token_data(errors: list[str],
     }
 
     :param errors: incidental error messages
-    :param service_url: the reference URL for obtaining JWT tokens
+    :param reference_url: the reference URL for obtaining JWT tokens
     :param logger: optional logger
     :return: the JWT token data, or 'None' if error
     """
     # inicialize the return variable
     result: dict[str, Any] | None = None
 
+    if logger:
+        logger.debug(msg=f"Retrieve JWT token data for reference URL '{reference_url}'")
     try:
-        result = __jwt_data.get_token_data(service_url=service_url,
+        result = __jwt_data.get_token_data(reference_url=reference_url,
                                            logger=logger)
+        if logger:
+            logger.debug(msg=f"Data is '{result}'")
     except Exception as e:
         if logger:
             logger.error(msg=str(e))
@@ -177,6 +195,9 @@ def jwt_get_claims(errors: list[str],
     # initialize the return variable
     result: dict[str, Any] | None = None
 
+    if logger:
+        logger.debug(msg=f"Retrieve claims for token '{token}'")
+
     try:
         result = __jwt_data.get_token_claims(token=token)
     except Exception as e:
@@ -198,6 +219,9 @@ def jwt_verify_request(request: Request,
     """
     # initialize the return variable
     result: Response | None = None
+    
+    if logger:
+        logger.debug(msg="Validate a JWT token")
 
     # retrieve the authorization from the request header
     auth_header: str = request.headers.get("Authorization")
@@ -206,6 +230,8 @@ def jwt_verify_request(request: Request,
     if auth_header and auth_header.startswith("Bearer "):
         # yes, extract and validate the JWT token
         token: str = auth_header.split(" ")[1]
+        if logger:
+            logger.debug(msg=f"Token is '{token}'")
         try:
             jwt_validate_token(token=token,
                                key=JWT_HS_SECRET_KEY or JWT_RSA_PUBLIC_KEY,
@@ -218,23 +244,24 @@ def jwt_verify_request(request: Request,
                               status=401)
     else:
         # no, report the error
+        if logger:
+            logger.error(msg="Request header has no 'Bearer' data")
         result = Response(response="Authorization failed",
                           status=401)
 
     return result
 
 
-# @flask_app.route(rule="/jwt-service",
-#                  methods=["POST"])
-def jwt_service(service_url: str = None,
-                service_params: dict[str, Any] = None) -> Response:
+def jwt_service(reference_url: str = None,
+                service_params: dict[str, Any] = None,
+                logger: Logger = None) -> Response:
     """
     Entry point for obtaining JWT tokens.
 
     In order to be serviced, the invoker must send, as parameter *service_params* or in the body of the request,
     a JSON containing:
     {
-      "service-url": "<url>",                               - the JWT reference URL (if not as parameter)
+      "reference-url": "<url>",                             - the JWT reference URL (if not as parameter)
       "<custom-claim-key-1>": "<custom-claim-value-1>",     - the registered custom claims
       ...
       "<custom-claim-key-n>": "<custom-claim-value-n>"
@@ -246,13 +273,20 @@ def jwt_service(service_url: str = None,
       "expires_in": <seconds-to-expiration>
     }
 
-    :param service_url: the JWT reference URL, alternatively passed in JSON
+    :param reference_url: the JWT reference URL, alternatively passed in JSON
     :param service_params: the optional JSON containing the request parameters (defaults to JSON in body)
+    :param logger: optional logger
     :return: the requested JWT token, along with its duration.
     """
     # declare the return variable
     result: Response
 
+    if logger:
+        msg: str = "Service a JWT request"
+        if request:
+            msg += f" from '{request.base_url}'"
+        logger.debug(msg=msg)
+
     # obtain the parameters
     # noinspection PyUnusedLocal
     params: dict[str, Any] = service_params or {}
@@ -262,10 +296,13 @@ def jwt_service(service_url: str = None,
 
     # validate the parameters
     valid: bool = False
-    if not service_url:
-        service_url = params.get("service-url")
-    if service_url:
-        item_data: dict[str, dict[str, Any]] = __jwt_data.retrieve_access_data(service_url=service_url)
+    if not reference_url:
+        reference_url = params.get("reference-url")
+    if reference_url:
+        if logger:
+            logger.debug(msg=f"Reference URL is '{reference_url}'")
+        item_data: dict[str, dict[str, Any]] = __jwt_data.retrieve_access_data(reference_url=reference_url,
+                                                                               logger=logger)
         if item_data:
             valid = True
             custom_claims: dict[str, Any] = item_data.get("custom-claims")
@@ -277,12 +314,18 @@ def jwt_service(service_url: str = None,
     # obtain the token data
     if valid:
         try:
-            token_data: dict[str, Any] = __jwt_data.get_token_data(service_url=service_url)
+            token_data: dict[str, Any] = __jwt_data.get_token_data(reference_url=reference_url,
+                                                                   logger=logger)
             result = jsonify(token_data)
         except Exception as e:
+            # validation failed
+            if logger:
+                logger.error(msg=str(e))
             result = Response(response=str(e),
                               status=401)
     else:
+        if logger:
+            logger.debug(msg=f"Invalid parameters {service_params}")
         result = Response(response="Invalid parameters",
                           status=401)