pypomes-jwt 0.9.1__py3-none-any.whl → 0.9.3__py3-none-any.whl

pypomes_jwt/__init__.py

@@ -9,8 +9,8 @@ from .jwt_constants import (
 from .jwt_pomes import (
     jwt_needed, jwt_verify_request,
     jwt_assert_account, jwt_set_account, jwt_remove_account,
-    jwt_issue_token, jwt_issue_tokens, jwt_get_claims,
-    jwt_validate_token, jwt_revoke_token
+    jwt_issue_token, jwt_issue_tokens, jwt_refresh_tokens,
+    jwt_get_claims, jwt_validate_token, jwt_revoke_token
 )
 
 __all__ = [
@@ -24,8 +24,8 @@ __all__ = [
     # jwt_pomes
     "jwt_needed", "jwt_verify_request",
     "jwt_assert_account", "jwt_set_account", "jwt_remove_account",
-    "jwt_issue_token", "jwt_issue_tokens", "jwt_get_claims",
-    "jwt_validate_token", "jwt_revoke_token"
+    "jwt_issue_token", "jwt_issue_tokens", "jwt_refresh_tokens",
+    "jwt_get_claims", "jwt_validate_token", "jwt_revoke_token"
 ]
 
 from importlib.metadata import version

pypomes_jwt/jwt_pomes.py

@@ -61,7 +61,7 @@ def jwt_verify_request(request: Request,
             logger.debug(msg="Bearer token was retrieved")
         errors: list[str] = []
         jwt_validate_token(errors=errors,
-                           nature=["A"],
+                           natures=["A"],
                            token=token)
         if errors:
             err_msg = "; ".join(errors)
@@ -157,20 +157,20 @@ def jwt_remove_account(account_id: str,
 
 def jwt_validate_token(errors: list[str] | None,
                        token: str,
-                       nature: list[str] = None,
+                       natures: list[str] = None,
                        account_id: str = None,
                        logger: Logger = None) -> dict[str, Any] | None:
     """
     Verify if *token* ia a valid JWT token.
 
     Raise an appropriate exception if validation failed.
-    if *nature* is provided, it is checked whether *token* has been locally issued and is of a appropriate nature.
-    A token issued locally has the header claim *kid* starting with "A" (for *Access*) or "R" (for *Refresh*),
-    followed by its id in the token database.
+    if *nature* is provided, verify whether *token* has been locally issued and is of a appropriate nature.
+    A token issued locally has the header claim *kid* starting with *A* (for *Access*) or *R* (for *Refresh*),
+    followed by its id in the token database, or as a single letter in the range *[B-Z]*, less *R*.
 
     :param errors: incidental error messages
     :param token: the token to be validated
-    :param nature: one of more prefixes identifying the nature of locally issued tokens
+    :param natures: one or more prefixes 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 if is valid, *None* otherwise
@@ -188,7 +188,7 @@ def jwt_validate_token(errors: list[str] | None,
     op_errors: list[str] = []
 
     # retrieve token data from database
-    if nature and not (token_kid and token_kid[0:1] in nature):
+    if natures and not (token_kid and token_kid[0:1] in natures):
         op_errors.append("Invalid token")
     elif token_kid and len(token_kid) > 1 and token_kid[0:1].isupper() and token[1:].isdigit():
         # token was likely issued locally
@@ -263,7 +263,7 @@ def jwt_revoke_token(errors: list[str] | None,
 
     :param errors: incidental error messages
     :param account_id: the account identification
-    :param refresh_token: the token to be revolked
+    :param refresh_token: the token to be revoked
     :param logger: optional logger
     :return: *True* if operation could be performed, *False* otherwise
     """
@@ -276,7 +276,7 @@ def jwt_revoke_token(errors: list[str] | None,
     op_errors: list[str] = []
     token_claims: dict[str, Any] = jwt_validate_token(errors=op_errors,
                                                       token=refresh_token,
-                                                      nature=["A", "R"],
+                                                      natures=["A", "R"],
                                                       account_id=account_id,
                                                       logger=logger)
     if not op_errors:
@@ -303,22 +303,22 @@ def jwt_issue_token(errors: list[str] | None,
                     account_id: str,
                     nature: str,
                     duration: int,
-                    claims: dict[str, Any],
                     grace_interval: int = None,
+                    claims: dict[str, Any] = None,
                     logger: Logger = None) -> str:
     """
     Issue or refresh, and return, a JWT token associated with *account_id*, of the specified *nature*.
 
-    The parameter *nature* must be a single uppercase, unaccented letter, different from "A"
-    (used to indicate *access* tokens) and *R* (used to indicate *refresh* tokens).
+    The parameter *nature* must be a single letter in the range *[B-Z]*, less *R*
+    (*A* is reserved for *access* tokens, and *R* for *refresh* tokens).
     The parameter *duration* specifies the token's validity interval (at least 60 seconds).
-    The token's *claims* should contain the claim *iss*.
+    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 (a single uppercase, unaccented letter different from "A" and "R")
+    :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: the token's claims (must contain at least the claim "iss")
+    :param claims: optional token's claims
     :param grace_interval: optional interval for the token to become active (in seconds)
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
@@ -327,7 +327,7 @@ def jwt_issue_token(errors: list[str] | None,
     result: str | None = None
 
     if logger:
-        logger.debug(msg=f"Issue a JWT token for '{account_id}'")
+        logger.debug(msg=f"Issuing a JWT token for '{account_id}'")
     op_errors: list[str] = []
 
     try:
@@ -355,13 +355,14 @@ def jwt_issue_token(errors: list[str] | None,
 def jwt_issue_tokens(errors: list[str] | None,
                      account_id: str,
                      account_claims: dict[str, Any] = None,
-                     refresh_token: str = None,
                      logger: Logger = None) -> dict[str, Any]:
     """
     Issue the JWT tokens associated with *account_id*, for access and refresh operations.
 
-    If *refresh_token* is provided, its claims are used on issuing the new tokens,
-    and claims in *account_claims*, if any, are ignored.
+    If *refresh_token* is provided, its claims are used on issuing the new tokens, and
+    claims in *account_claims*, if any, are ignored. Furthermore, these claims are ignored,
+    if provided in *account_claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
+    Other claims specified therein may supercede registered account-related claims.
 
     Structure of the return data:
     {
@@ -374,7 +375,6 @@ def jwt_issue_tokens(errors: list[str] | None,
     :param errors: incidental error messages
     :param account_id: the account identification
     :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
     """
@@ -382,33 +382,82 @@ def jwt_issue_tokens(errors: list[str] | None,
     result: dict[str, Any] | None = None
 
     if logger:
-        logger.debug(msg=f"Return JWT token data for '{account_id}'")
+        logger.debug(msg=f"Issuing a pair of JWT tokens for '{account_id}'")
+    op_errors: list[str] = []
+
+    try:
+        result = __jwt_registry.issue_tokens(account_id=account_id,
+                                             account_claims=account_claims,
+                                             logger=logger)
+        if logger:
+            logger.debug(msg=f"Token data is '{result}'")
+    except Exception as e:
+        # token issuing failed
+        op_errors.append(str(e))
+
+    if op_errors:
+        if logger:
+            logger.error("; ".join(op_errors))
+        if isinstance(errors, list):
+            errors.extend(op_errors)
+
+    return result
+
+
+def jwt_refresh_tokens(errors: list[str] | None,
+                       account_id: str,
+                       refresh_token: str = None,
+                       logger: Logger = None) -> dict[str, Any]:
+    """
+    Issue the JWT tokens associated with *account_id*, for access and refresh operations.
+
+    The claims in *refresh-token* are used on issuing the new tokens.
+
+    Structure of the return data:
+    {
+      "access_token": <jwt-token>,
+      "created_in": <timestamp>,
+      "expires_in": <seconds-to-expiration>,
+      "refresh_token": <jwt-token>
+    }
+
+    :param errors: incidental error messages
+    :param account_id: the account identification
+    :param refresh_token: the base refresh token
+    :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"Refreshing a pair of JWT tokens for '{account_id}'")
     op_errors: list[str] = []
 
     # verify whether this refresh token is legitimate
     if refresh_token:
-        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: dict[str, Any] = (jwt_validate_token(errors=op_errors,
+                                                             token=refresh_token,
+                                                             natures=["R"],
+                                                             account_id=account_id,
+                                                             logger=logger) or {}).get("payload")
+        # revoke current refresh token
+        if account_claims and jwt_revoke_token(errors=errors,
+                                               account_id=account_id,
+                                               refresh_token=refresh_token,
+                                               logger=logger):
+            account_claims.pop("exp", None)
             account_claims.pop("iat", None)
-            account_claims.pop("jti", None)
             account_claims.pop("iss", None)
-            account_claims.pop("exp", None)
+            account_claims.pop("jti", None)
             account_claims.pop("nbt", None)
-
-    if not op_errors:
-        try:
-            result = __jwt_registry.issue_tokens(account_id=account_id,
-                                                 account_claims=account_claims,
-                                                 logger=logger)
-            if logger:
-                logger.debug(msg=f"Token data is '{result}'")
-        except Exception as e:
-            # token issuing failed
-            op_errors.append(str(e))
+            account_claims.pop("sub", None)
+            # issue tokens
+            result = jwt_issue_tokens(errors=errors,
+                                      account_id=account_id,
+                                      account_claims=account_claims)
+    else:
+        op_errors.append("Refresh token was not provided")
 
     if op_errors:
         if logger:

pypomes_jwt/jwt_registry.py

@@ -81,12 +81,12 @@ class JwtRegistry:
        "nonce": <string>        # value used to associate a client session with a token
 
     The token header has these items:
-      "alg": <string>           # the algorithm used to sign the token (one of 'HS256', 'HS512', 'RSA256', 'RSA512')
-      "typ": <string>           # the token type (fixed to 'JWT'
+      "alg": <string>           # the algorithm used to sign the token (one of *HS256*, *HS51*', *RSA256*, *RSA512*)
+      "typ": <string>           # the token type (fixed to *JWT*
       "kid": <string>           # a reference to the token type and the key to its location in the token database
 
-    If issued by the local server, "kid" holds the key to the corresponding record in the token database.
-    It starts with *A* for (*Access*) or *R* (for *Refresh*) followed its integer key.
+    If issued by the local server, "kid" holds the key to the corresponding record in the token database,
+    if starting with *A* for (*Access*) or *R* (for *Refresh*), followed an integer.
     """
     def __init__(self) -> None:
         """
@@ -111,7 +111,7 @@ class JwtRegistry:
         Add to storage the parameters needed to produce and validate JWT tokens for *account_id*.
 
         The parameter *claims* may contain account-related claims, only. Ideally, it should contain,
-        at a minimum, "birthdate", "email", "gender", "name", and "roles".
+        at a minimum, *birthdate*, *email*, *gender*, *name*, and *roles*.
         If the token provider is local, then the token-related claims are created at token issuing time.
         If the token provider is remote, all claims are sent to it at token request time.
 
@@ -178,21 +178,21 @@ class JwtRegistry:
                     account_id: str,
                     nature: str,
                     duration: int,
-                    claims: dict[str, Any],
                     grace_interval: int = None,
+                    claims: dict[str, Any] = None,
                     logger: Logger = None) -> str:
         """
         Issue an return a JWT token associated with *account_id*.
 
-        The parameter *nature* must be a single uppercase, unaccented letter, different from "A"
-        (used to indicate *access* tokens) and *R* (used to indicate *refresh* tokens).
+        The parameter *nature* must be a single letter in the range *[B-Z]*, less *R*
+        (*A* is reserved for *access* tokens, and *R* for *refresh* tokens).
         The parameter *duration* specifies the token's validity interval (at least 60 seconds).
-        The token's *claims* should contain the claim *iss*.
+        These claims are ignored, if specified in *claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
 
         :param account_id: the account identification
-        :param nature: the token's nature (a single uppercase, unaccented letter different from "A" and "R")
+        :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: the token's claims (must contain at least the claim "iss")
+        :param claims: optional token's claims
         :param grace_interval: optional interval for the token to become active (in seconds)
         :param logger: optional logger
         :return: the JWT token
@@ -212,13 +212,16 @@ class JwtRegistry:
                 logger.error(err_msg)
             raise RuntimeError(err_msg)
 
-        # make sure account data exists
-        self.__get_account_data(account_id=account_id,
-                                logger=logger)
+        # obtain the account data in storage (may raise an exception)
+        account_data: dict[str, Any] = self.__get_account_data(account_id=account_id,
+                                                               logger=logger)
         # issue the token
-        current_claims: dict[str, Any] = claims.copy()
+        current_claims: dict[str, Any] = {}
+        if claims:
+            current_claims.update(claims)
         current_claims["jti"] = str_random(size=32,
                                            chars=string.ascii_letters + string.digits)
+        current_claims["iss"] = account_data.get("reference-url")
         current_claims["sub"] = account_id
         just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
         current_claims["iat"] = just_now
@@ -245,6 +248,9 @@ class JwtRegistry:
         """
         Issue and return the JWT access and refresh tokens for *account_id*.
 
+        These claims are ignored, if specified in *account_claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
+        Other claims specified therein may supercede registered account-related claims.
+
         Structure of the return data:
         {
           "access_token": <jwt-token>,
@@ -262,7 +268,7 @@ class JwtRegistry:
         # initialize the return variable
         result: dict[str, Any] | None = None
 
-        # process the data in storage
+        # process the account data in storage
         with (self.access_lock):
             account_data: dict[str, Any] = self.__get_account_data(account_id=account_id,
                                                                    logger=logger)

{pypomes_jwt-0.9.1.dist-info → pypomes_jwt-0.9.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.9.1
+Version: 0.9.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

pypomes_jwt-0.9.3.dist-info/RECORD

@@ -0,0 +1,8 @@
+pypomes_jwt/__init__.py,sha256=t6TzpvttDuLMaKSGuBicOf9cZU4Y0N9mtby3ThS4lt8,1398
+pypomes_jwt/jwt_constants.py,sha256=IQV39AiZKGuU8XxZBgJ-KJZQZ_mmnxyOnRZeuxlqDRk,4045
+pypomes_jwt/jwt_pomes.py,sha256=UnEkOUN0vovlenyb8ROvpM96Qf0Mx-JRle-EooyTy7k,21734
+pypomes_jwt/jwt_registry.py,sha256=TANRyMGxoO7sR2EwO_bgVzIMjM3OHAr7olvnSmMtwCQ,26020
+pypomes_jwt-0.9.3.dist-info/METADATA,sha256=DrB3ku89ZNBM3FBpnnnmDv-Rvi4F70sIXj0M5zJnQOM,632
+pypomes_jwt-0.9.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pypomes_jwt-0.9.3.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
+pypomes_jwt-0.9.3.dist-info/RECORD,,

pypomes_jwt-0.9.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-pypomes_jwt/__init__.py,sha256=6AISZOs7JP695PnMSsYyKfoiMXvSzXffkv3nKw7qA1A,1356
-pypomes_jwt/jwt_constants.py,sha256=IQV39AiZKGuU8XxZBgJ-KJZQZ_mmnxyOnRZeuxlqDRk,4045
-pypomes_jwt/jwt_pomes.py,sha256=qm8COn0vPts-I0n5pnA_5phm-5wkV82dicAf3bvQ8R8,19734
-pypomes_jwt/jwt_registry.py,sha256=MWJy1bxXdgVySmBYJCdK_721U6tJXk3BHrYVChLjCR8,25613
-pypomes_jwt-0.9.1.dist-info/METADATA,sha256=b5EpwtK-c0JCi3QjRt6W_QoQXg8nYkUjJHbD0pTGgF4,632
-pypomes_jwt-0.9.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pypomes_jwt-0.9.1.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
-pypomes_jwt-0.9.1.dist-info/RECORD,,