pypomes-jwt 0.9.1__tar.gz → 0.9.2__tar.gz

{pypomes_jwt-0.9.1 → pypomes_jwt-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.9.1
+Version: 0.9.2
 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.1 → pypomes_jwt-0.9.2}/pyproject.toml

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

{pypomes_jwt-0.9.1 → pypomes_jwt-0.9.2}/src/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
@@ -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
@@ -360,8 +360,10 @@ def jwt_issue_tokens(errors: list[str] | None,
     """
     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:
     {
@@ -389,15 +391,16 @@ def jwt_issue_tokens(errors: list[str] | None,
     if refresh_token:
         account_claims = (jwt_validate_token(errors=op_errors,
                                              token=refresh_token,
-                                             nature=["R"],
+                                             natures=["R"],
                                              account_id=account_id,
                                              logger=logger) or {}).get("payload")
         if account_claims:
+            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)
+            account_claims.pop("sub", None)
 
     if not op_errors:
         try:

{pypomes_jwt-0.9.1 → pypomes_jwt-0.9.2}/src/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)