pypomes-jwt 1.2.6__tar.gz → 1.2.8__tar.gz

{pypomes_jwt-1.2.6 → pypomes_jwt-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 1.2.6
+Version: 1.2.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
@@ -11,7 +11,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Requires-Dist: cryptography>=45.0.6
-Requires-Dist: flask>=3.1.1
+Requires-Dist: flask>=3.1.2
 Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: pypomes-core>=2.6.5
-Requires-Dist: pypomes-db>=2.4.8
+Requires-Dist: pypomes-core>=2.7.0
+Requires-Dist: pypomes-db>=2.5.8

{pypomes_jwt-1.2.6 → pypomes_jwt-1.2.8}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_jwt"
-version = "1.2.6"
+version = "1.2.8"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -20,10 +20,10 @@ classifiers = [
 ]
 dependencies = [
     "cryptography>=45.0.6",
-    "Flask>=3.1.1",
+    "Flask>=3.1.2",
     "PyJWT>=2.10.1",
-    "pypomes_core>=2.6.5",
-    "pypomes_db>=2.4.8"
+    "pypomes_core>=2.7.0",
+    "pypomes_db>=2.5.8"
 ]
 
 [project.urls]

{pypomes_jwt-1.2.6 → pypomes_jwt-1.2.8}/src/pypomes_jwt/jwt_pomes.py

@@ -6,7 +6,7 @@ from logging import Logger
 from pypomes_core import exc_format
 from pypomes_db import (
     DbEngine, db_connect, db_commit,
-    db_rollback, db_select, db_delete
+    db_rollback, db_close, db_select, db_delete
 )
 from typing import Any
 
@@ -54,8 +54,7 @@ def jwt_verify_request(request: Request) -> Response:
     if auth_header and auth_header.startswith("Bearer "):
         # yes, extract and validate the JWT access token
         token: str = auth_header.split(" ")[1]
-        claims: dict[str, Any] = jwt_validate_token(errors=None,
-                                                    token=token,
+        claims: dict[str, Any] = jwt_validate_token(token=token,
                                                     nature="A")
         if claims:
             login: str = request.values.get("login")
@@ -129,10 +128,10 @@ def jwt_remove_account(account_id: str,
                                          logger=logger)
 
 
-def jwt_validate_token(errors: list[str] | None,
-                       token: str,
+def jwt_validate_token(token: str,
                        nature: str = None,
                        account_id: str = None,
+                       errors: list[str] = None,
                        logger: Logger = None) -> dict[str, Any] | None:
     """
     Verify if *token* is a valid JWT token.
@@ -147,10 +146,10 @@ def jwt_validate_token(errors: list[str] | None,
     On success, return the token's claims (*header* and *payload*), as documented in *jwt_get_claims()*
     On failure, *errors* will contain the reason(s) for rejecting *token*.
 
-    :param errors: incidental error messages
     :param token: the token to be validated
     :param nature: prefix identifying the nature of locally issued tokens
     :param account_id: optionally, validate the token's account owner
+    :param errors: incidental error messages
     :param logger: optional logger
     :return: The token's claims (*header* and *payload*) if it is valid, *None* otherwise
     """
@@ -188,12 +187,12 @@ def jwt_validate_token(errors: list[str] | None,
             where_data: dict[str, Any] = {JwtDbConfig.COL_KID: int(token_kid[1:])}
             if account_id:
                 where_data[JwtDbConfig.COL_ACCOUNT] = account_id
-            recs: list[tuple[str]] = db_select(errors=op_errors,
-                                               sel_stmt=f"SELECT {JwtDbConfig.COL_ALGORITHM}, "
+            recs: list[tuple[str]] = db_select(sel_stmt=f"SELECT {JwtDbConfig.COL_ALGORITHM}, "
                                                         f"{JwtDbConfig.COL_DECODER} "
                                                         f"FROM {JwtDbConfig.TABLE}",
                                                where_data=where_data,
                                                engine=DbEngine(JwtDbConfig.ENGINE),
+                                               errors=op_errors,
                                                logger=logger)
             if recs:
                 token_alg = recs[0][0]
@@ -255,18 +254,18 @@ def jwt_validate_token(errors: list[str] | None,
     return result
 
 
-def jwt_revoke_token(errors: list[str] | None,
-                     account_id: str,
+def jwt_revoke_token(account_id: str,
                      token: str,
+                     errors: list[str] = None,
                      logger: Logger = None) -> bool:
     """
     Revoke the *refresh_token* associated with *account_id*.
 
     Revoke operations require access to a database table defined by *JWT_DB_TABLE*.
 
-    :param errors: incidental error messages
     :param account_id: the account identification
     :param token: the token to be revoked
+    :param errors: incidental error messages
     :param logger: optional logger
     :return: *True* if operation could be performed, *False* otherwise
     """
@@ -277,22 +276,22 @@ def jwt_revoke_token(errors: list[str] | None,
         logger.debug(msg=f"Revoking token of account '{account_id}'")
 
     op_errors: list[str] = []
-    token_claims: dict[str, Any] = jwt_validate_token(errors=op_errors,
-                                                      token=token,
+    token_claims: dict[str, Any] = jwt_validate_token(token=token,
                                                       account_id=account_id,
+                                                      errors=op_errors,
                                                       logger=logger)
     if not op_errors:
         token_kid: str = token_claims["header"].get("kid")
         if token_kid[0:1] not in ["A", "R"]:
             op_errors.append("Invalid token")
         else:
-            db_delete(errors=op_errors,
-                      delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
+            db_delete(delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
                       where_data={
                           JwtDbConfig.COL_KID: int(token_kid[1:]),
                           JwtDbConfig.COL_ACCOUNT: account_id
                       },
                       engine=DbEngine(JwtDbConfig.ENGINE),
+                      errors=op_errors,
                       logger=logger)
     if op_errors:
         if logger:
@@ -305,12 +304,12 @@ def jwt_revoke_token(errors: list[str] | None,
     return result
 
 
-def jwt_issue_token(errors: list[str] | None,
-                    account_id: str,
+def jwt_issue_token(account_id: str,
                     nature: str,
                     duration: int,
                     lead_interval: int = None,
                     claims: dict[str, Any] = None,
+                    errors: list[str] = None,
                     logger: Logger = None) -> str:
     """
     Issue or refresh, and return, a JWT token associated with *account_id*, of the specified *nature*.
@@ -320,12 +319,12 @@ def jwt_issue_token(errors: list[str] | None,
     The parameter *duration* specifies the token's validity interval (at least 60 seconds).
     These claims are ignored, if specified in *claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
 
-    :param errors: incidental error messages
     :param account_id: the account identification
     :param nature: the token's nature, must be a single letter in the range *[B-Z]*, less *R*
     :param duration: the number of seconds for the token to remain valid (at least 60 seconds)
     :param claims: optional token's claims
     :param lead_interval: optional interval for the token to become active (in seconds)
+    :param errors: incidental error messages
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
     """
@@ -359,9 +358,9 @@ def jwt_issue_token(errors: list[str] | None,
     return result
 
 
-def jwt_issue_tokens(errors: list[str] | None,
-                     account_id: str,
+def jwt_issue_tokens(account_id: str,
                      account_claims: dict[str, Any] = None,
+                     errors: list[str] = None,
                      logger: Logger = None) -> dict[str, Any]:
     """
     Issue the JWT token pair associated with *account_id*, for access and refresh operations.
@@ -377,9 +376,9 @@ def jwt_issue_tokens(errors: list[str] | None,
       "refresh-token": <jwt-token>
     }
 
-    :param errors: incidental error messages
     :param account_id: the account identification
     :param account_claims: if provided, may supercede currently registered account-related claims
+    :param errors: incidental error messages
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
     """
@@ -413,9 +412,9 @@ def jwt_issue_tokens(errors: list[str] | None,
     return result
 
 
-def jwt_refresh_tokens(errors: list[str] | None,
-                       account_id: str,
+def jwt_refresh_tokens(account_id: str,
                        refresh_token: str,
+                       errors: list[str] = None,
                        logger: Logger = None) -> dict[str, Any]:
     """
     Refresh the JWT token pair associated with *account_id*, for access and refresh operations.
@@ -446,24 +445,23 @@ def jwt_refresh_tokens(errors: list[str] | None,
     # assert the refresh token
     if refresh_token:
         # is the refresh token valid ?
-        token_claims: dict[str, Any] = jwt_validate_token(errors=op_errors,
-                                                          token=refresh_token,
+        token_claims: dict[str, Any] = jwt_validate_token(token=refresh_token,
                                                           nature="R",
                                                           account_id=account_id,
+                                                          errors=op_errors,
                                                           logger=logger)
         if token_claims:
             # yes, proceed
             token_kid: str = token_claims["header"].get("kid")
 
             # start the database transaction
-            db_conn: Any = db_connect(errors=op_errors,
-                                      autocommit=False,
+            db_conn: Any = db_connect(autocommit=False,
                                       engine=DbEngine(JwtDbConfig.ENGINE),
+                                      errors=op_errors,
                                       logger=logger)
             if db_conn:
                 # delete current refresh token
-                db_delete(errors=op_errors,
-                          delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
+                db_delete(delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
                           where_data={
                               JwtDbConfig.COL_KID: int(token_kid[1:]),
                               JwtDbConfig.COL_ACCOUNT: account_id
@@ -471,6 +469,7 @@ def jwt_refresh_tokens(errors: list[str] | None,
                           engine=DbEngine(JwtDbConfig.ENGINE),
                           connection=db_conn,
                           committable=False,
+                          errors=op_errors,
                           logger=logger)
 
                 # issue the token pair
@@ -492,13 +491,14 @@ def jwt_refresh_tokens(errors: list[str] | None,
 
                 # wrap-up the transaction
                 if op_errors:
-                    db_rollback(errors=op_errors,
-                                connection=db_conn,
+                    db_rollback(connection=db_conn,
                                 logger=logger)
                 else:
-                    db_commit(errors=op_errors,
-                              connection=db_conn,
+                    db_commit(connection=db_conn,
+                              errors=op_errors,
                               logger=logger)
+                db_close(connection=db_conn,
+                         logger=logger)
     else:
         # refresh token not found
         op_errors.append("Refresh token was not provided")
@@ -512,8 +512,8 @@ def jwt_refresh_tokens(errors: list[str] | None,
     return result
 
 
-def jwt_get_claims(errors: list[str] | None,
-                   token: str,
+def jwt_get_claims(token: str,
+                   errors: list[str] = None,
                    logger: Logger = None) -> dict[str, Any] | None:
     """
     Retrieve the claims set of a JWT *token*.
@@ -548,8 +548,8 @@ def jwt_get_claims(errors: list[str] | None,
         }
       }
 
-    :param errors: incidental error messages
     :param token: the token to be inspected for claims
+    :param errors: incidental error messages
     :param logger: optional logger
     :return: the token's claimset, or *None* if error
     """

{pypomes_jwt-1.2.6 → pypomes_jwt-1.2.8}/src/pypomes_jwt/jwt_providers.py

@@ -38,8 +38,8 @@ def provider_register(provider_id: str,
     HTTP Basic Authorization scheme, wherein the credentials are B64-encoded and send in the request headers.
 
     Optional constant key-value pairs (such as ['Content-Type', 'application/x-www-form-urlencoded']), to be
-    added to the request headers, may be specified in *header_data*. Likewise, optional constant key-value pairs
-    (such as ['grant-type', 'client_crdentials']), to be added to the request body, may be specified in *body_data*.
+    added to the request headers, may be specified in *headers_data*. Likewise, optional constant key-value pairs
+    (such as ['grant_type', 'client_credentials']), to be added to the request body, may be specified in *body_data*.
 
     :param provider_id: the provider's identification
     :param access_url: the url to request authentication tokens with
@@ -96,9 +96,12 @@ def provider_get_token(errors: list[str] | None,
             try:
                 # typical return on a token request:
                 # {
-                #   "expires_in": <number-of-seconds>,
                 #   "token_type": "bearer",
-                #   "access_token": <the-token>
+                #   "access_token": <str>,
+                #   "expires_in": <number-of-seconds>,
+                #   optional data:
+                #   "refresh_token": <str>,
+                #   "refresh_expires_in": <nomber-of-seconds>
                 # }
                 response: Response = requests.post(url=url,
                                                    data=body_data,

{pypomes_jwt-1.2.6 → pypomes_jwt-1.2.8}/src/pypomes_jwt/jwt_registry.py

@@ -133,8 +133,7 @@ class JwtRegistry:
             account_data = self.access_registry.pop(account_id, None)
 
         # remove from database
-        db_delete(errors=None,
-                  delete_stmt=f"DELETE FROM {JwtDbConfig}",
+        db_delete(delete_stmt=f"DELETE FROM {JwtDbConfig}",
                   where_data={JwtDbConfig.COL_ACCOUNT: account_id},
                   engine=DbEngine(JwtDbConfig.ENGINE),
                   logger=logger)
@@ -264,9 +263,9 @@ class JwtRegistry:
                                             headers={"kid": "R0"})
 
             # make sure to have a database connection
-            curr_conn: Any = db_conn or db_connect(errors=errors,
-                                                   autocommit=False,
+            curr_conn: Any = db_conn or db_connect(autocommit=False,
                                                    engine=DbEngine(JwtDbConfig.ENGINE),
+                                                   errors=errors,
                                                    logger=logger)
             if curr_conn:
                 # persist the candidate token (may raise an exception)
@@ -280,24 +279,22 @@ class JwtRegistry:
                                            algorithm=JwtConfig.DEFAULT_ALGORITHM.value,
                                            headers={"kid": f"R{token_id}"})
                 # persist it
-                db_update(errors=errors,
-                          update_stmt=f"UPDATE {JwtDbConfig.TABLE}",
+                db_update(update_stmt=f"UPDATE {JwtDbConfig.TABLE}",
                           update_data={JwtDbConfig.COL_TOKEN: refresh_token},
                           where_data={JwtDbConfig.COL_KID: token_id},
                           engine=DbEngine(JwtDbConfig.ENGINE),
                           connection=curr_conn,
-                          committable=False,
+                          errors=errors,
                           logger=logger)
 
                 # wrap-up the transaction
                 if not db_conn:
                     if errors:
-                        db_rollback(errors=errors,
-                                    connection=curr_conn,
+                        db_rollback(connection=curr_conn,
                                     logger=logger)
                     else:
-                        db_commit(errors=errors,
-                                  connection=curr_conn,
+                        db_commit(connection=curr_conn,
+                                  errors=errors,
                                   logger=logger)
             if errors:
                 raise RuntimeError("; ".join(errors))
@@ -340,7 +337,7 @@ class JwtRegistry:
     @staticmethod
     def jwt_persist_token(account_id: str,
                           jwt_token: str,
-                          db_conn: Any,
+                          db_conn: Any = None,
                           logger: Logger = None) -> int:
         """
         Persist the given token, making sure that the account limit is complied with.
@@ -349,7 +346,9 @@ class JwtRegistry:
         If a token's expiration timestamp is in the past, it is removed from storage. If the maximum number
         of active tokens for *account_id* has been reached, the oldest active one is alse removed,
         to make room for the new *jwt_token*.
-        The provided database connection *db_conn* indicates that this operation is part of a larger transaction.
+
+        If provided, *db_conn* indicates that this operation is part of a larger database transaction.
+        Otherwise, the database transaction's scope is limited to this operation.
 
         :param account_id: the account identification
         :param jwt_token: the JWT token to persist
@@ -364,19 +363,18 @@ class JwtRegistry:
         errors: list[str] = []
         # noinspection PyTypeChecker
         recs: list[tuple[int, str, str, str]] = \
-            db_select(errors=errors,
-                      sel_stmt=f"SELECT {JwtDbConfig.COL_KID}, {JwtDbConfig.COL_TOKEN} "
+            db_select(sel_stmt=f"SELECT {JwtDbConfig.COL_KID}, {JwtDbConfig.COL_TOKEN} "
                                f"FROM {JwtDbConfig.TABLE}",
                       where_data={JwtDbConfig.COL_ACCOUNT: account_id},
                       engine=DbEngine(JwtDbConfig.ENGINE),
                       connection=db_conn,
-                      committable=False,
+                      errors=errors,
                       logger=logger)
         if errors:
             raise RuntimeError("; ".join(errors))
 
         if logger:
-            logger.debug(msg=f"Read {len(recs)} token from storage for account '{account_id}'")
+            logger.debug(msg=f"Retrieved {len(recs)} tokens from storage for account '{account_id}'")
         # remove the expired tokens
         just_now: int = int(datetime.now(tz=UTC).timestamp())
         oldest_ts: int = sys.maxsize
@@ -385,8 +383,8 @@ class JwtRegistry:
         for rec in recs:
             token: str = rec[1]
             token_id: int = rec[0]
-            token_payload: dict[str, Any] = (jwt_get_claims(errors=errors,
-                                                            token=token,
+            token_payload: dict[str, Any] = (jwt_get_claims(token=token,
+                                                            errors=errors,
                                                             logger=logger) or {}).get("payload")
             if errors:
                 raise RuntimeError("; ".join(errors))
@@ -404,12 +402,11 @@ class JwtRegistry:
 
         # remove expired tokens from persistence
         if expired:
-            db_delete(errors=errors,
-                      delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
+            db_delete(delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
                       where_data={JwtDbConfig.COL_KID: expired},
                       engine=DbEngine(JwtDbConfig.ENGINE),
                       connection=db_conn,
-                      committable=False,
+                      errors=errors,
                       logger=logger)
             if errors:
                 raise RuntimeError("; ".join(errors))
@@ -419,12 +416,11 @@ class JwtRegistry:
 
         if 0 < JwtConfig.ACCOUNT_LIMIT.value <= len(recs) - len(expired):
             # delete the oldest token to make way for the new one
-            db_delete(errors=errors,
-                      delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
+            db_delete(delete_stmt=f"DELETE FROM {JwtDbConfig.TABLE}",
                       where_data={JwtDbConfig.COL_KID: oldest_id},
                       engine=DbEngine(JwtDbConfig.ENGINE),
                       connection=db_conn,
-                      committable=False,
+                      errors=errors,
                       logger=logger)
             if errors:
                 raise RuntimeError("; ".join(errors))
@@ -432,8 +428,7 @@ class JwtRegistry:
                 logger.debug(msg="Oldest active token of account "
                                  f"'{account_id}' removed from storage")
         # persist token
-        col_kid: int = db_insert(errors=errors,
-                                 insert_stmt=f"INSERT INTO {JwtDbConfig.TABLE}",
+        col_kid: int = db_insert(insert_stmt=f"INSERT INTO {JwtDbConfig.TABLE}",
                                  insert_data={
                                      JwtDbConfig.COL_ACCOUNT: account_id,
                                      JwtDbConfig.COL_TOKEN: jwt_token,
@@ -443,14 +438,13 @@ class JwtRegistry:
                                  return_cols={JwtDbConfig.COL_KID: int},
                                  engine=DbEngine(JwtDbConfig.ENGINE),
                                  connection=db_conn,
-                                 committable=False,
+                                 errors=errors,
                                  logger=logger)
         if errors:
             raise RuntimeError("; ".join(errors))
 
         # obtain and return the token's storage id
-        reply: list[tuple[int]] = db_select(errors=errors,
-                                            sel_stmt=f"SELECT {JwtDbConfig.COL_KID} "
+        reply: list[tuple[int]] = db_select(sel_stmt=f"SELECT {JwtDbConfig.COL_KID} "
                                                      f"FROM {JwtDbConfig.TABLE}",
                                             where_data={JwtDbConfig.COL_KID: col_kid},
                                             min_count=1,
@@ -458,6 +452,7 @@ class JwtRegistry:
                                             engine=DbEngine(JwtDbConfig.ENGINE),
                                             connection=db_conn,
                                             committable=False,
+                                            errors=errors,
                                             logger=logger)
         if errors:
             raise RuntimeError("; ".join(errors))