pypomes-jwt 0.8.2__tar.gz → 0.8.3__tar.gz

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.8.2
+Version: 0.8.3
 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
@@ -13,3 +13,4 @@ Requires-Python: >=3.12
 Requires-Dist: cryptography>=44.0.2
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pypomes-core>=1.8.3
+Requires-Dist: pypomes-db>=1.9.5

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_jwt"
-version = "0.8.2"
+version = "0.8.3"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -21,8 +21,8 @@ classifiers = [
 dependencies = [
     "PyJWT>=2.10.1",
     "cryptography>=44.0.2",
-    "pypomes_core>=1.8.3"
-    # "pypomes_db>=1.9.5"
+    "pypomes_core>=1.8.3",
+    "pypomes_db>=1.9.5"
 ]
 
 [project.urls]

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/src/pypomes_jwt/__init__.py

@@ -1,27 +1,29 @@
 from .jwt_constants import (
     JWT_DB_ENGINE, JWT_DB_HOST, JWT_DB_NAME,
     JWT_DB_PORT, JWT_DB_USER, JWT_DB_PWD,
-    JWT_DB_TABLE, JWT_DB_COL_ACCOUNT, JWT_DB_COL_TOKEN,
+    JWT_DB_TABLE, JWT_DB_COL_KID, JWT_DB_COL_ACCOUNT,
+    JWT_DB_COL_ALGORITHM, JWT_DB_COL_DECODER, JWT_DB_COL_TOKEN,
     JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
     JWT_ENCODING_KEY, JWT_DECODING_KEY
 )
 from .jwt_pomes import (
     jwt_needed, jwt_verify_request,
-    jwt_get_tokens, jwt_get_claims, jwt_validate_token,
-    jwt_assert_account, jwt_set_account, jwt_remove_account, jwt_revoke_token
+    jwt_assert_account, jwt_set_account, jwt_remove_account,
+    jwt_get_tokens, jwt_get_claims, jwt_validate_token, jwt_revoke_token
 )
 
 __all__ = [
     # jwt_constants
     "JWT_DB_ENGINE", "JWT_DB_HOST", "JWT_DB_NAME",
     "JWT_DB_PORT", "JWT_DB_USER", "JWT_DB_PWD",
-    "JWT_DB_TABLE", "JWT_DB_COL_ACCOUNT", "JWT_DB_COL_TOKEN",
+    "JWT_DB_TABLE", "JWT_DB_COL_KID", "JWT_DB_COL_ACCOUNT",
+    "JWT_DB_COL_ALGORITHM", "JWT_DB_COL_DECODER", "JWT_DB_COL_TOKEN",
     "JWT_ACCESS_MAX_AGE", "JWT_REFRESH_MAX_AGE",
     "JWT_ENCODING_KEY", "JWT_DECODING_KEY",
     # jwt_pomes
     "jwt_needed", "jwt_verify_request",
-    "jwt_get_tokens", "jwt_get_claims", "jwt_validate_token",
-    "jwt_assert_account", "jwt_set_account", "jwt_remove_account", "jwt_revoke_token"
+    "jwt_assert_account", "jwt_set_account", "jwt_remove_account",
+    "jwt_get_tokens", "jwt_get_claims", "jwt_validate_token", "jwt_revoke_token"
 ]
 
 from importlib.metadata import version

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/src/pypomes_jwt/jwt_constants.py

@@ -5,7 +5,9 @@ from pypomes_core import (
     APP_PREFIX,
     env_get_str, env_get_bytes, env_get_int
 )
+from pypomes_db import DbEngine, db_setup
 from secrets import token_bytes
+from sys import stderr
 from typing import Final
 
 # database specs for token persistence
@@ -18,14 +20,14 @@ JWT_DB_CLIENT: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_CLIENT")  # fo
 JWT_DB_DRIVER: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_DRIVER")  # for SQLServer, only
 JWT_DB_TABLE: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_TABLE")
 JWT_DB_COL_ACCOUNT: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ACCOUNT")
-JWT_DB_COL_HASH: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_HASH")
+JWT_DB_COL_ALGORITHM: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_ALGORITHM")
+JWT_DB_COL_DECODER: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_DECODER")
+JWT_DB_COL_KID: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_KID")
 JWT_DB_COL_TOKEN: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_COL_TOKEN")
-# define the database engine
-__db_engine: str | None = env_get_str(key=f"{APP_PREFIX}_JWT_DB_ENGINE")
-if __db_engine:
-    from pypomes_db import DbEngine, db_setup, db_assert_access, db_delete
-    from sys import stderr
-    if db_setup(engine=DbEngine(__db_engine),
+
+# define and validate the database engine
+JWT_DB_ENGINE: Final[DbEngine] = DbEngine(env_get_str(key=f"{APP_PREFIX}_JWT_DB_ENGINE"))
+if not db_setup(engine=JWT_DB_ENGINE,
                 db_name=JWT_DB_NAME,
                 db_user=JWT_DB_USER,
                 db_pwd=JWT_DB_PWD,
@@ -33,22 +35,11 @@ if __db_engine:
                 db_port=JWT_DB_PORT,
                 db_client=JWT_DB_CLIENT,
                 db_driver=JWT_DB_DRIVER):
-        __errors: list[str] = []
-        if not db_assert_access(errors=__errors) or \
-            db_delete(errors=__errors,
-                      delete_stmt=f"DELETE FROM {JWT_DB_TABLE}") is None:
-            stderr.write(f"{'; '.join(__errors)}\n")
-            __db_engine = None
-    else:
-        stderr.write("Invalid database parameters\n")
-        __db_engine = None
-# if set to 'None', no further attempt will be made to access the database
-JWT_DB_ENGINE: Final[DbEngine] = DbEngine(__db_engine) if __db_engine else None
+    stderr.write("Invalid database parameters\n")
 
-# one of HS256, HS512, RSA256, RSA512
+# one of HS256, HS512, RS256, RS512
 JWT_DEFAULT_ALGORITHM: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DEFAULT_ALGORITHM",
                                                 def_value="RS256")
-
 # recommended: between 5 min and 1 hour (set to 5 min)
 JWT_ACCESS_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_ACCESS_MAX_AGE",
                                              def_value=300)

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/src/pypomes_jwt/jwt_data.py

@@ -1,17 +1,19 @@
-import hashlib
 import jwt
 import requests
 import string
+import sys
 from datetime import datetime, timezone
 from logging import Logger
 from pypomes_core import str_random
+from pypomes_db import db_connect, db_commit, db_update, db_delete
 from requests import Response
 from threading import Lock
 from typing import Any
 
 from .jwt_constants import (
-    JWT_DEFAULT_ALGORITHM, JWT_ENCODING_KEY, JWT_DECODING_KEY, JWT_ACCOUNT_LIMIT,
-    JWT_DB_ENGINE, JWT_DB_TABLE, JWT_DB_COL_ACCOUNT, JWT_DB_COL_HASH, JWT_DB_COL_TOKEN
+    JWT_DEFAULT_ALGORITHM, JWT_ACCOUNT_LIMIT, JWT_ENCODING_KEY, JWT_DECODING_KEY,
+    JWT_DB_TABLE, JWT_DB_COL_KID, JWT_DB_COL_ACCOUNT,
+    JWT_DB_COL_ALGORITHM, JWT_DB_COL_DECODER, JWT_DB_COL_TOKEN
 )
 
 
@@ -149,12 +151,10 @@ class JwtData:
         with self.access_lock:
             account_data = self.access_data.pop(account_id, None)
 
-        if account_data and JWT_DB_ENGINE:
-            from pypomes_db import db_delete
-            db_delete(errors=None,
-                      delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
-                      where_data={JWT_DB_COL_ACCOUNT: account_id},
-                      logger=logger)
+        db_delete(errors=None,
+                  delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
+                  where_data={JWT_DB_COL_ACCOUNT: account_id},
+                  logger=logger)
         if logger:
             if account_data:
                 logger.debug(f"Removed JWT data for '{account_id}'")
@@ -192,8 +192,7 @@ 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: error accessing the revocation database, or
-                              the remote JWT provider failed to return a token
+        :raises RuntimeError: error accessing the token database
         """
         # initialize the return variable
         result: dict[str, Any] | None = None
@@ -209,8 +208,6 @@ class JwtData:
                 current_claims: dict[str, Any] = account_data.get("claims").copy()
                 if account_claims:
                     current_claims.update(account_claims)
-
-                # obtain new tokens
                 current_claims["jti"] = str_random(size=32,
                                                    chars=string.ascii_letters + string.digits)
                 current_claims["sub"] = account_id
@@ -233,41 +230,52 @@ class JwtData:
                                                 timeout=account_data.get("request-timeout"),
                                                 logger=logger)
                     if errors:
-                        raise RuntimeError(" - ".join(errors))
+                        raise RuntimeError("; ".join(errors))
                 else:
                     # JWT service is being provided locally
                     just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
                     current_claims["iat"] = just_now
-                    token_header: dict[str, Any] = None \
-                        if JWT_DEFAULT_ALGORITHM not in ["RS256", "RS512"] \
-                        else {"kid": JWT_DECODING_KEY.hex()}
-
-                    # issue the access token first
-                    current_claims["nat"] = "A"
-                    current_claims["exp"] = just_now + account_data.get("access-max-age")
-                    # may raise an exception
-                    access_token: str = jwt.encode(payload=current_claims,
-                                                   key=JWT_ENCODING_KEY,
-                                                   algorithm=JWT_DEFAULT_ALGORITHM,
-                                                   headers=token_header)
 
-                    # then issue the refresh token
+                    # issue a candidate refresh token first, and persist it
                     current_claims["exp"] = just_now + account_data.get("refresh-max-age")
-                    current_claims["nat"] = "R"
                     # may raise an exception
                     refresh_token: str = jwt.encode(payload=current_claims,
                                                     key=JWT_ENCODING_KEY,
-                                                    algorithm=JWT_DEFAULT_ALGORITHM,
-                                                    headers=token_header)
-                    if JWT_DB_ENGINE:
-                        # persist the refresh token
-                        _jwt_persist_token(errors=errors,
-                                           account_id=account_id,
-                                           jwt_token=refresh_token,
-                                           logger=logger)
-                        if errors:
-                            raise RuntimeError("; ".join(errors))
+                                                    algorithm=JWT_DEFAULT_ALGORITHM)
+                    # obtain a DB connection (may raise an exception)
+                    db_conn: Any = db_connect(errors=errors,
+                                              logger=logger)
+                    # persist the candidate token (may raise an exception)
+                    token_id: int = _jwt_persist_token(errors=errors,
+                                                       account_id=account_id,
+                                                       jwt_token=refresh_token,
+                                                       db_conn=db_conn,
+                                                       logger=logger)
+                    # issue the definitive refresh token
+                    refresh_token = jwt.encode(payload=current_claims,
+                                               key=JWT_ENCODING_KEY,
+                                               algorithm=JWT_DEFAULT_ALGORITHM,
+                                               headers={"kid": str(token_id)})
+                    # persist it
+                    db_update(errors=errors,
+                              update_stmt=f"UPDATE {JWT_DB_TABLE}",
+                              update_data={JWT_DB_COL_TOKEN: refresh_token},
+                              where_data={JWT_DB_COL_KID: token_id},
+                              connection=db_conn,
+                              logger=logger)
+                    # commit the transaction
+                    db_commit(errors=errors,
+                              connection=db_conn,
+                              logger=logger)
+                    if errors:
+                        raise RuntimeError("; ".join(errors))
 
+                    # issue the access token
+                    current_claims["exp"] = just_now + account_data.get("access-max-age")
+                    # may raise an exception
+                    access_token: str = jwt.encode(payload=current_claims,
+                                                   key=JWT_ENCODING_KEY,
+                                                   algorithm=JWT_DEFAULT_ALGORITHM)
                     # return the token data
                     result = {
                         "access_token": access_token,
@@ -342,64 +350,109 @@ def _jwt_request_token(errors: list[str],
 def _jwt_persist_token(errors: list[str],
                        account_id: str,
                        jwt_token: str,
-                       logger: Logger = None) -> None:
+                       db_conn: Any = None,
+                       logger: Logger = None) -> int:
     """
     Persist the given token, making sure that the account limit is adhered to.
 
+    The tokens in storage, associated with *account_id*, are examined for their expiration timestamp.
+    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*.
+
+    If *db_conn* is provided, then all DB operations will be carried out in the scope of a single transaction.
+
     :param errors: incidental errors
     :param account_id: the account identification
     :param jwt_token: the JWT token to persist
+    :param db_conn: the database connection to use
     :param logger: optional logger
+    :return: the storage id of the inserted token
+    :raises RuntimeError: error accessing the revocation database
     """
     from pypomes_db import db_select, db_insert, db_delete
     from .jwt_pomes import jwt_get_claims
 
     # retrieve the account's tokens
-    recs: list[tuple[str]] = db_select(errors=errors,
-                                       sel_stmt=f"SELECT {JWT_DB_COL_HASH}, {JWT_DB_COL_TOKEN} FROM {JWT_DB_TABLE} ",
-                                       where_data={JWT_DB_COL_ACCOUNT: account_id})
-    if not errors:
+    # noinspection PyTypeChecker
+    recs: list[tuple[int, str, str, str]] = \
+        db_select(errors=errors,
+                  sel_stmt=f"SELECT {JWT_DB_COL_KID}, {JWT_DB_COL_TOKEN} "
+                           f"FROM {JWT_DB_TABLE}",
+                  where_data={JWT_DB_COL_ACCOUNT: account_id},
+                  connection=db_conn)
+    if errors:
+        raise RuntimeError("; ".join(errors))
+
+    if logger:
+        logger.debug(msg=f"Read {len(recs)} token from storage for account '{account_id}'")
+    # remove the expired tokens
+    oldest: int = sys.maxsize
+    surplus: int | None = None
+    expired: list[int] = []
+    for rec in recs:
+        token: str = rec[1]
+        token_kid: int = rec[0]
+        token_claims: dict[str, Any] = jwt_get_claims(errors=errors,
+                                                      token=token,
+                                                      validate=False,
+                                                      logger=logger)
+        if errors:
+            raise RuntimeError("; ".join(errors))
+
+        exp: int = token_claims["payload"].get("exp")
+        if exp < datetime.now(tz=timezone.utc).timestamp():
+            expired.append(token_kid)
+        elif exp < oldest:
+            oldest = exp
+            surplus = token_kid
+
+    # remove expired tokens from persistence
+    # ruff: noqa: SIM102
+    if expired:
+        db_delete(errors=errors,
+                  delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
+                  where_data={JWT_DB_COL_KID: expired},
+                  connection=db_conn,
+                  logger=logger)
+        if errors:
+            raise RuntimeError("; ".join(errors))
+        if logger:
+            logger.debug(msg=f"{len(expired)} tokens of account "
+                             f"'{account_id}' removed from storage")
+
+    if 0 < JWT_ACCOUNT_LIMIT <= len(recs) - len(expired):
+        # delete the oldest persisted token to make way for the new one
+        db_delete(errors=errors,
+                  delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
+                  where_data={JWT_DB_COL_KID: surplus},
+                  connection=db_conn,
+                  logger=logger)
+        if errors:
+            raise RuntimeError("; ".join(errors))
         if logger:
-            logger.debug(msg=f"Read {len(recs)} token from storage for account '{account_id}'")
-        # remove the expired tokens
-        expired: list[str] = []
-        for rec in recs:
-            token: str = rec[1]
-            token_hash: str = rec[0]
-            token_claims: dict[str, Any] = jwt_get_claims(errors=errors,
-                                                          token=token,
-                                                          validate=False,
-                                                          logger=logger)
-            if errors:
-                break
-            exp: int = token_claims["payload"]["exp"]
-            if exp < datetime.now(tz=timezone.utc).timestamp():
-                expired.append(token_hash)
-
-        if not errors:
-            # remove expired tokens from persistence
-            # ruff: noqa: SIM102
-            if expired:
-                if db_delete(errors=errors,
-                             delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
-                             where_data={
-                                JWT_DB_COL_ACCOUNT: account_id,
-                                JWT_DB_COL_HASH: expired
-                             },
-                             logger=logger) is not None:
-                    if logger:
-                        logger.debug(msg=f"{len(expired)} tokens removed from storage")
-                    if 0 < JWT_ACCOUNT_LIMIT <= len(recs) - len(expired):
-                        errors.append("Maximum number of active sessions "
-                                      f"({JWT_ACCOUNT_LIMIT}) exceeded for account '{account_id}'")
-            # persist token
-            if not errors:
-                # ruff: noqa: S324
-                hasher = hashlib.new(name="md5",
-                                     data=jwt_token.encode())
-                token_hash: str = hasher.digest().hex()
-                db_insert(errors=errors,
-                          insert_stmt=f"INSERT INTO {JWT_DB_TABLE}",
-                          insert_data={JWT_DB_COL_ACCOUNT: account_id,
-                                       JWT_DB_COL_HASH: token_hash,
-                                       JWT_DB_COL_TOKEN: jwt_token})
+            logger.debug(msg="Oldest active token of account "
+                             f"'{account_id}' removed from storage")
+    # persist token
+    db_insert(errors=errors,
+              insert_stmt=f"INSERT INTO {JWT_DB_TABLE}",
+              insert_data={JWT_DB_COL_ACCOUNT: account_id,
+                           JWT_DB_COL_TOKEN: jwt_token,
+                           JWT_DB_COL_ALGORITHM: JWT_DEFAULT_ALGORITHM,
+                           JWT_DB_COL_DECODER: JWT_DECODING_KEY.hex()},
+              connection=db_conn,
+              logger=logger)
+    if errors:
+        raise RuntimeError("; ".join(errors))
+
+    # obtain the token's storage id
+    reply: list[tuple[int]] = db_select(errors=errors,
+                                        sel_stmt=f"SELECT {JWT_DB_COL_KID} "
+                                                 f"FROM {JWT_DB_TABLE}",
+                                        where_data={JWT_DB_COL_TOKEN: jwt_token},
+                                        connection=db_conn,
+                                        logger=logger)
+    if errors:
+        raise RuntimeError("; ".join(errors))
+
+    return reply[0][0]

{pypomes_jwt-0.8.2 → pypomes_jwt-0.8.3}/src/pypomes_jwt/jwt_pomes.py

@@ -1,13 +1,14 @@
-import hashlib
 import jwt
 from flask import Request, Response, request
 from logging import Logger
+from pypomes_db import db_select, db_delete
 from typing import Any, Literal
 
+from . import JWT_DB_COL_ACCOUNT
 from .jwt_constants import (
     JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
     JWT_DEFAULT_ALGORITHM, JWT_DECODING_KEY,
-    JWT_DB_ENGINE, JWT_DB_TABLE, JWT_DB_COL_HASH
+    JWT_DB_TABLE, JWT_DB_COL_KID, JWT_DB_COL_ALGORITHM, JWT_DB_COL_DECODER
 )
 from .jwt_data import JwtData
 
@@ -73,7 +74,6 @@ def jwt_verify_request(request: Request,
             logger.error(msg=err_msg)
         result = Response(response="Authorization failed",
                           status=401)
-
     return result
 
 
@@ -157,7 +157,8 @@ def jwt_remove_account(account_id: str,
 def jwt_validate_token(errors: list[str] | None,
                        token: str,
                        nature: Literal["A", "R"] = None,
-                       logger: Logger = None) -> bool:
+                       account_id: str = None,
+                       logger: Logger = None) -> dict[str, Any] | None:
     """
     Verify if *token* ia a valid JWT token.
 
@@ -166,48 +167,87 @@ def jwt_validate_token(errors: list[str] | None,
     :param errors: incidental error messages
     :param token: the token to be validated
     :param nature: optionally validate the token's nature ("A": access token, "R": refresh token)
+    :param account_id: optionally, validate the token's account owner
     :param logger: optional logger
-    :return: *True* if token is valid, *False* otherwise
+    :return: The token's claims (header and payload) if if is valid, *None* otherwise
     """
+    # initialize the return variable
+    result: dict[str, Any] | None = None
     if logger:
         logger.debug(msg=f"Validate JWT token '{token}'")
 
-    err_msg: str | None = None
-    try:
-        # raises:
-        #   InvalidTokenError: token is invalid
-        #   InvalidKeyError: authentication key is not in the proper format
-        #   ExpiredSignatureError: token and refresh period have expired
-        #   InvalidSignatureError: signature does not match the one provided as part of the token
-        claims: dict[str, Any] = jwt.decode(jwt=token,
-                                            key=JWT_DECODING_KEY,
-                                            algorithms=[JWT_DEFAULT_ALGORITHM])
-        if nature and nature != claims.get("nat"):
-            nat: str = "an access" if nature == "A" else "a refresh"
-            err_msg = f"Token is not {nat} token"
-        elif JWT_DB_ENGINE and claims.get("nat") == "R":
-            from pypomes_db import db_exists
-            # ruff: noqa: S324
-            hasher = hashlib.new(name="md5",
-                                 data=token.encode())
-            token_hash: str = hasher.digest().hex()
-            if not db_exists(errors=errors,
-                             table=JWT_DB_TABLE,
-                             where_data={JWT_DB_COL_HASH: token_hash},
-                             logger=logger):
-                err_msg = "Token is not valid"
-    except Exception as e:
-        err_msg = str(e)
+    # extract needed data from token header
+    token_header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
+    token_kid: int = int(token_header.get("kid") or 0)
+    token_alg: str | None = None
+    token_decoder: bytes | None = None
+    op_errors: list[str] = []
 
-    if err_msg:
+    # retrieve token data from database
+    if (nature == "R" and not token_kid) or (nature == "A" and token_kid):
+        nat: str = "an access" if nature == "A" else "a refresh"
+        op_errors.append(f"Token is not {nat} token")
+    elif token_kid:
+        where_data: dict[str, str] = {JWT_DB_COL_KID: token_kid}
+        if account_id:
+            where_data[JWT_DB_COL_ACCOUNT] = account_id
+        recs: list[tuple[str]] = db_select(errors=op_errors,
+                                           sel_stmt=f"SELECT {JWT_DB_COL_ALGORITHM}, {JWT_DB_COL_DECODER} "
+                                                    f"FROM {JWT_DB_TABLE}",
+                                           where_data=where_data,
+                                           logger=logger)
+        if recs:
+            token_alg = recs[0][0]
+            token_decoder = bytes.fromhex(recs[0][1])
+        else:
+            op_errors.append("Invalid token")
+    else:
+        token_alg = JWT_DEFAULT_ALGORITHM
+        token_decoder = JWT_DECODING_KEY
+
+        # validate the token
+    if not op_errors:
+        try:
+            # raises:
+            #   InvalidTokenError: token is invalid
+            #   InvalidKeyError: authentication key is not in the proper format
+            #   ExpiredSignatureError: token and refresh period have expired
+            #   InvalidSignatureError: signature does not match the one provided as part of the token
+            #   ImmatureSignatureError: 'nbf' or 'iat' claim represents a timestamp in the future
+            #   InvalidAudienceError: 'aud' claim does not match one of the expected audience
+            #   InvalidAlgorithmError: the specified algorithm is not recognized
+            #   InvalidIssuerError: 'iss' claim does not match the expected issuer
+            #   InvalidIssuedAtError: 'iat' claim is non-numeric
+            #   MissingRequiredClaimError: a required claim is not contained in the claimset
+            payload: dict[str, Any] = jwt.decode(jwt=token,
+                                                 options={
+                                                     "verify_signature": True,
+                                                     "verify_exp": True,
+                                                     "verify_nbf": True
+                                                 },
+                                                 key=token_decoder,
+                                                 require=["exp", "nbf"],
+                                                 algorithms=token_alg)
+            if account_id and payload.get("sub") != account_id:
+                op_errors.append("Token does not belong to account")
+            else:
+                result = {
+                    "header": token_header,
+                    "payload": payload
+                }
+        except Exception as e:
+            op_errors.append(str(e))
+
+    if op_errors:
+        err_msg: str = "; ".join(op_errors)
         if logger:
             logger.error(msg=err_msg)
         if isinstance(errors, list):
-            errors.append(err_msg)
+            errors.extend(op_errors)
     elif logger:
         logger.debug(msg=f"Token '{token}' is valid")
 
-    return err_msg is None
+    return result
 
 
 def jwt_revoke_token(errors: list[str] | None,
@@ -232,25 +272,20 @@ def jwt_revoke_token(errors: list[str] | None,
         logger.debug(msg=f"Revoking refresh token of '{account_id}'")
 
     op_errors: list[str] = []
-    if JWT_DB_ENGINE:
-        from pypomes_db import db_exists, db_delete
-        # ruff: noqa: S324
-        hasher = hashlib.new(name="md5",
-                             data=refresh_token.encode())
-        token_hash: str = hasher.digest().hex()
-        if db_exists(errors=op_errors,
-                     table=JWT_DB_TABLE,
-                     where_data={JWT_DB_COL_HASH: token_hash},
-                     logger=logger):
-            db_delete(errors=errors,
-                      delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
-                      where_data={JWT_DB_COL_HASH: token_hash},
-                      logger=logger)
-        elif not op_errors:
-            op_errors.append("Token was not found")
-    else:
-        op_errors.append("Database access for token revocation has not been specified")
-
+    token_claims: dict[str, Any] = jwt_validate_token(errors=op_errors,
+                                                      token=refresh_token,
+                                                      nature="R",
+                                                      account_id=account_id,
+                                                      logger=logger)
+    if not op_errors:
+        token_kid: int = int(token_claims["header"].get("kid") or 0)
+        db_delete(errors=op_errors,
+                  delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
+                  where_data={
+                      JWT_DB_COL_KID: token_kid,
+                      JWT_DB_COL_ACCOUNT: account_id
+                  },
+                  logger=logger)
     if op_errors:
         if logger:
             logger.error(msg="; ".join(op_errors))
@@ -283,7 +318,7 @@ def jwt_get_tokens(errors: list[str] | None,
 
     :param errors: incidental error messages
     :param account_id: the account identification
-    :param account_claims: if provided, may supercede registered custom claims
+    :param account_claims: if provided, may supercede registered claims
     :param refresh_token: if provided, defines a token refresh operation
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
@@ -296,31 +331,24 @@ def jwt_get_tokens(errors: list[str] | None,
     op_errors: list[str] = []
     if refresh_token:
         # verify whether this refresh token is legitimate
-        if JWT_DB_ENGINE:
-            from pypomes_db import db_exists
-            # ruff: noqa: S324
-            hasher = hashlib.new(name="md5",
-                                 data=refresh_token.encode())
-            token_hash: str = hasher.digest().hex()
-            if db_exists(errors=op_errors,
-                         table=JWT_DB_TABLE,
-                         where_data={JWT_DB_COL_HASH: token_hash},
-                         logger=logger) is False:
-                op_errors.append("Invalid refresh token")
-
-        if not op_errors:
-            account_claims = jwt_get_claims(errors=op_errors,
-                                            token=refresh_token)
-            if not op_errors and (account_claims.get("payload") or {}).get("nat") != "R":
-                op_errors.append("Invalid parameters")
-
+        account_claims = (jwt_validate_token(errors=op_errors,
+                                             token=refresh_token,
+                                             nature="R",
+                                             account_id=account_id,
+                                             logger=logger) or {}).get("payload")
+        if account_claims:
+            account_claims.pop("iat", None)
+            account_claims.pop("jti", None)
+            account_claims.pop("iss", None)
+            account_claims.pop("exp", None)
+            account_claims.pop("nbt", None)
     if not op_errors:
         try:
             result = __jwt_data.issue_tokens(account_id=account_id,
                                              account_claims=account_claims,
                                              logger=logger)
             if logger:
-                logger.debug(msg=f"Data is '{result}'")
+                logger.debug(msg=f"Token data is '{result}'")
         except Exception as e:
             # token issuing failed
             op_errors.append(str(e))
@@ -336,8 +364,8 @@ def jwt_get_tokens(errors: list[str] | None,
 
 def jwt_get_claims(errors: list[str] | None,
                    token: str,
-                   validate: bool = True,
-                   logger: Logger = None) -> dict[str, Any]:
+                   validate: bool = False,
+                   logger: Logger = None) -> dict[str, Any] | None:
     """
     Obtain and return the claims set of a JWT *token*.
 
@@ -373,7 +401,7 @@ def jwt_get_claims(errors: list[str] | None,
 
     :param errors: incidental error messages
     :param token: the token to be inspected for claims
-    :param validate: If *True*, verifies the token's data
+    :param validate: If *True*, verifies the token's data (defaults to *False*)
     :param logger: optional logger
     :return: the token's claimset, or *None* if error
     """
@@ -384,26 +412,19 @@ def jwt_get_claims(errors: list[str] | None,
         logger.debug(msg=f"Retrieve claims for token '{token}'")
 
     try:
-        # retrieve the token's payload
+        # retrieve the token's claims
         if validate:
-            payload: dict[str, Any] = jwt.decode(jwt=token,
-                                                 options={
-                                                     "verify_signature": True,
-                                                     "verify_exp": True,
-                                                     "verify_nbf": True
-                                                 },
-                                                 key=JWT_DECODING_KEY,
-                                                 require=["exp", "nbf"],
-                                                 algorithms=[JWT_DEFAULT_ALGORITHM])
+            result = jwt_validate_token(errors=errors,
+                                        token=token,
+                                        logger=logger)
         else:
+            header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
             payload: dict[str, Any] = jwt.decode(jwt=token,
                                                  options={"verify_signature": False})
-        # retrieve the token's header
-        header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
-        result = {
-            "header": header,
-            "payload": payload
-        }
+            result = {
+                "header": header,
+                "payload": payload
+            }
     except Exception as e:
         if logger:
             logger.error(msg=str(e))