pypomes-jwt 0.9.4__tar.gz → 0.9.6__tar.gz

{pypomes_jwt-0.9.4 → pypomes_jwt-0.9.6}/PKG-INFO

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

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

{pypomes_jwt-0.9.4 → pypomes_jwt-0.9.6}/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,
-                           natures=["A"],
+                           nature="A",
                            token=token)
         if errors:
             err_msg = "; ".join(errors)
@@ -89,47 +89,48 @@ def jwt_assert_account(account_id: str) -> bool:
 
 
 def jwt_set_account(account_id: str,
-                    reference_url: str,
                     claims: dict[str, Any],
                     access_max_age: int = JWT_ACCESS_MAX_AGE,
                     refresh_max_age: int = JWT_REFRESH_MAX_AGE,
                     grace_interval: int = None,
                     request_timeout: int = None,
-                    remote_provider: bool = None,
+                    remote_url: str = None,
                     logger: Logger = None) -> None:
     """
-    Set the data needed to obtain JWT tokens for *account_id*.
+    Establish the data needed to obtain JWT tokens for *account_id*.
 
     :param account_id: the account identification
-    :param reference_url: the reference URL (for remote providers, URL to obtain and validate the JWT tokens)
     :param claims: the JWT claimset, as key-value pairs
     :param access_max_age: access token duration, in seconds
     :param refresh_max_age: refresh token duration, in seconds
     :param grace_interval: optional time to wait for token to be valid, in seconds
     :param request_timeout: timeout for the requests to the reference URL
-    :param remote_provider: whether the JWT provider is a remote server
+    :param remote_url: remote server's URL to obtain the JWT tokens from
     :param logger: optional logger
     """
     if logger:
         logger.debug(msg=f"Register account data for '{account_id}'")
 
-    # extract the claims provided in the reference URL's query string
-    pos: int = reference_url.find("?")
-    if pos > 0:
-        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]
+    # extract the claims provided in the remote_url URL's query string
+    if remote_url:
+        pos: int = remote_url.find("?")
+        if pos > 0:
+            claims = claims or {}
+            params: list[str] = remote_url[pos+1:].split(sep="&")
+            for param in params:
+                key: str = param.split("=")[0]
+                value: str = param.split("=")[1]
+                claims[key] = value
+            remote_url = remote_url[:pos]
 
     # register the JWT service
     __jwt_registry.add_account(account_id=account_id,
-                               reference_url=reference_url,
                                claims=claims,
                                access_max_age=access_max_age,
                                refresh_max_age=refresh_max_age,
                                grace_interval=grace_interval,
                                request_timeout=request_timeout,
-                               remote_provider=remote_provider,
+                               remote_url=remote_url,
                                logger=logger)
 
 
@@ -151,7 +152,7 @@ def jwt_remove_account(account_id: str,
 
 def jwt_validate_token(errors: list[str] | None,
                        token: str,
-                       natures: list[str] = None,
+                       nature: str = None,
                        account_id: str = None,
                        logger: Logger = None) -> dict[str, Any] | None:
     """
@@ -164,7 +165,7 @@ def jwt_validate_token(errors: list[str] | None,
 
     :param errors: incidental error messages
     :param token: the token to be validated
-    :param natures: one or more prefixes identifying the nature of locally issued tokens
+    :param nature: prefix 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
@@ -182,9 +183,10 @@ def jwt_validate_token(errors: list[str] | None,
     op_errors: list[str] = []
 
     # retrieve token data from database
-    if natures and not (token_kid and token_kid[0:1] in natures):
+    if nature and not (token_kid and token_kid[0:1] == nature):
         op_errors.append("Invalid token")
-    elif token_kid and len(token_kid) > 1 and token_kid[0:1].isupper() and token[1:].isdigit():
+    elif token_kid and len(token_kid) > 1 and \
+            token_kid[0:1] in ["A", "R"] and token[1:].isdigit():
         # token was likely issued locally
         where_data: dict[str, Any] = {JWT_DB_COL_KID: int(token_kid[1:])}
         if account_id:
@@ -270,18 +272,20 @@ 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,
-                                                      natures=["A", "R"],
                                                       account_id=account_id,
                                                       logger=logger)
     if not op_errors:
         token_kid: str = token_claims["header"].get("kid")
-        db_delete(errors=op_errors,
-                  delete_stmt=f"DELETE FROM {JWT_DB_TABLE}",
-                  where_data={
-                      JWT_DB_COL_KID: int(token_kid[1:]),
-                      JWT_DB_COL_ACCOUNT: account_id
-                  },
-                  logger=logger)
+        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 {JWT_DB_TABLE}",
+                      where_data={
+                          JWT_DB_COL_KID: int(token_kid[1:]),
+                          JWT_DB_COL_ACCOUNT: account_id
+                      },
+                      logger=logger)
     if op_errors:
         if logger:
             logger.error(msg="; ".join(op_errors))
@@ -351,12 +355,10 @@ def jwt_issue_tokens(errors: list[str] | None,
                      account_claims: dict[str, Any] = None,
                      logger: Logger = None) -> dict[str, Any]:
     """
-    Issue the JWT tokens associated with *account_id*, for access and refresh operations.
+    Issue the JWT token pair 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. 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.
+    These claims are ignored, if provided in *account_claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
+    Other claims specified therein may supercede currently registered account-related claims.
 
     Structure of the return data:
     {
@@ -368,7 +370,7 @@ 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 account_claims: if provided, may supercede currently registered account-related claims
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
     """
@@ -376,7 +378,7 @@ def jwt_issue_tokens(errors: list[str] | None,
     result: dict[str, Any] | None = None
 
     if logger:
-        logger.debug(msg=f"Issuing a pair of JWT tokens for '{account_id}'")
+        logger.debug(msg=f"Issuing a JWT token pair for '{account_id}'")
     op_errors: list[str] = []
 
     try:
@@ -400,10 +402,10 @@ def jwt_issue_tokens(errors: list[str] | None,
 
 def jwt_refresh_tokens(errors: list[str] | None,
                        account_id: str,
-                       refresh_token: str = None,
+                       refresh_token: str,
                        logger: Logger = None) -> dict[str, Any]:
     """
-    Issue the JWT tokens associated with *account_id*, for access and refresh operations.
+    Refresh the JWT token pair associated with *account_id*, for access and refresh operations.
 
     The claims in *refresh-token* are used on issuing the new tokens.
 
@@ -425,14 +427,14 @@ def jwt_refresh_tokens(errors: list[str] | None,
     result: dict[str, Any] | None = None
 
     if logger:
-        logger.debug(msg=f"Refreshing a pair of JWT tokens for '{account_id}'")
+        logger.debug(msg=f"Refreshing a JWT token pair for '{account_id}'")
     op_errors: list[str] = []
 
     # verify whether this refresh token is legitimate
     if refresh_token:
         account_claims: dict[str, Any] = (jwt_validate_token(errors=op_errors,
                                                              token=refresh_token,
-                                                             natures=["R"],
+                                                             nature="R",
                                                              account_id=account_id,
                                                              logger=logger) or {}).get("payload")
         # revoke current refresh token
@@ -440,12 +442,6 @@ def jwt_refresh_tokens(errors: list[str] | None,
                                                account_id=account_id,
                                                refresh_token=refresh_token,
                                                logger=logger):
-            account_claims.pop("exp", None)
-            account_claims.pop("iat", None)
-            account_claims.pop("iss", None)
-            account_claims.pop("jti", None)
-            account_claims.pop("nbt", None)
-            account_claims.pop("sub", None)
             # issue tokens
             result = jwt_issue_tokens(errors=errors,
                                       account_id=account_id,

{pypomes_jwt-0.9.4 → pypomes_jwt-0.9.6}/src/pypomes_jwt/jwt_registry.py

@@ -27,23 +27,22 @@ class JwtRegistry:
       - access_data: dictionary holding the JWT token data, organized by account id:
        {
          <account-id>: {
-           "reference-url":              # the reference URL
-           "remote-provider": <bool>,    # whether the JWT provider is a remote server
-           "request-timeout": <int>,     # in seconds - defaults to no timeout
-           "access-max-age": <int>,      # in seconds - defaults to JWT_ACCESS_MAX_AGE
-           "refresh-max-age": <int>,     # in seconds - defaults to JWT_REFRESH_MAX_AGE
-           "grace-interval": <int>       # time to wait for token to be valid, in seconds
-           "request-timeout": <int>      # timeout for the requests to the reference URL (in seconds)
+           "access-max-age": <int>,      # defaults to JWT_ACCESS_MAX_AGE (in seconds)
+           "refresh-max-age": <int>,     # defaults to JWT_REFRESH_MAX_AGE (in seconds)
+           "grace-interval": <int>,      # time to wait for token to be valid, in seconds
+           "request-timeout": <int>,     # timeout for the requests to the reference URL (in seconds)
+           "remote_url": <string>,       # remote server's URL to obtain the JWT tokens from
            "claims": {
-             "valid-from": <string>      # token's start (<YYYY-MM-DDThh:mm:ss+00:00>)
-             "valid-until": <string>     # token's finish (<YYYY-MM-DDThh:mm:ss+00:00>)
-             # optional
+             "iss": <string>,            # token'ss issuer
              "birthdate": <string>,      # subject's birth date
              "email": <string>,          # subject's email
              "gender": <string>,         # subject's gender
              "name": <string>,           # subject's name
              "roles": <List[str]>,       # subject roles
              "nonce": <string>,          # used to associate a Client session with a token
+             # output, only
+             "valid-from": <string>,     # token's start (<YYYY-MM-DDThh:mm:ss+00:00>)
+             "valid-until": <string>,    # token's finish (<YYYY-MM-DDThh:mm:ss+00:00>)
              ...
            }
          },
@@ -58,30 +57,30 @@ class JwtRegistry:
 
     Token-related claims are mostly required claims, and convey information about the token itself:
       # required
-      "exp": <timestamp>        # expiration time
-      "iat": <timestamp>        # issued at
-      "iss": <string>           # issuer (for remote providers, URL to obtain and validate the access tokens)
-      "jti": <string>           # JWT id
-      "sub": <string>           # subject (the account identification)
+      "exp": <timestamp>        expiration time
+      "iat": <timestamp>        issued at
+      "iss": <string>           token's issuer
+      "jti": <string>           JWT id
+      "sub": <string>           subject (the account identification)
       # optional
-      "aud": <string>           # token audience
-      "nbt": <timestamp>        # not before time
+      "aud": <string>           token audience
+      "nbt": <timestamp>        not before time
 
     Account-related claims are optional claims, and convey information about the registered account they belong to.
     Alhough they can be freely specified, these are some of the most commonly used claims:
-       "valid-from": <string>   # token's start (<YYYY-MM-DDThh:mm:ss+00:00>)
-       "valid-until": <string>  # token's finish (<YYYY-MM-DDThh:mm:ss+00.00>)
-       "birthdate": <string>    # subject's birth date
-       "email": <string>        # subject's email
-       "gender": <string>       # subject's gender
-       "name": <string>         # subject's name
-       "roles": <List[str]>     # subject roles
-       "nonce": <string>        # used to associate a client session with a token
+       "valid-from": <string>   token's start (<YYYY-MM-DDThh:mm:ss+00:00>)
+       "valid-until": <string>  token's finish (<YYYY-MM-DDThh:mm:ss+00.00>)
+       "birthdate": <string>    subject's birth date
+       "email": <string>        subject's email
+       "gender": <string>       subject's gender
+       "name": <string>         subject's name
+       "roles": <List[str]>     subject roles
+       "nonce": <string>        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*, *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
+      "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,
     if starting with *A* for (*Access*) or *R* (for *Refresh*), followed an integer.
@@ -95,13 +94,12 @@ class JwtRegistry:
 
     def add_account(self,
                     account_id: str,
-                    reference_url: str,
                     claims: dict[str, Any],
                     access_max_age: int,
                     refresh_max_age: int,
                     grace_interval: int | None,
                     request_timeout: int | None,
-                    remote_provider: bool | None,
+                    remote_url: str | None,
                     logger: Logger = None) -> None:
         """
         Add to storage the parameters needed to produce and validate JWT tokens for *account_id*.
@@ -112,25 +110,23 @@ class JwtRegistry:
         If the token provider is remote, all claims are sent to it at token request time.
 
         :param account_id: the account identification
-        :param reference_url: the reference URL (for remote providers, URL to obtain and validate the JWT tokens)
         :param claims: the JWT claimset, as key-value pairs
         :param access_max_age: access token duration, in seconds
         :param refresh_max_age: refresh token duration, in seconds
         :param grace_interval: time to wait for token to be valid, in seconds
         :param request_timeout: timeout for the requests to the reference URL (in seconds)
-        :param remote_provider: whether the JWT provider is a remote server
+        :param remote_url: remote server's URL to obtain the JWT tokens from
         :param logger: optional logger
         """
         # build and store the access data for the account
         with self.access_lock:
             if account_id not in self.access_data:
                 self.access_data[account_id] = {
-                    "reference-url": reference_url,
                     "access-max-age": access_max_age,
                     "refresh-max-age": refresh_max_age,
                     "grace-interval": grace_interval,
                     "request-timeout": request_timeout,
-                    "remote-provider": remote_provider,
+                    "remote-url": remote_url,
                     "claims": claims or {}
                 }
                 if logger:
@@ -195,8 +191,6 @@ class JwtRegistry:
         if not isinstance(nature, str) or \
                 len(nature) != 1 or nature < "A" or nature > "Z":
             err_msg: str = f"Invalid nature '{nature}'"
-        elif not isinstance(claims, dict) or "iss" not in claims:
-            err_msg = f"invalid claims '{claims}'"
         elif not isinstance(duration, int) or duration < 60:
             err_msg = f"Invalid duration '{duration}'"
         if err_msg:
@@ -209,11 +203,14 @@ class JwtRegistry:
                                                                logger=logger)
         # issue the token
         current_claims: dict[str, Any] = {}
+        iss: str = account_data["claims"].get("iss")
+        if iss:
+            current_claims["iss"] = iss
         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
@@ -238,9 +235,9 @@ class JwtRegistry:
                      account_claims: dict[str, Any] = None,
                      logger: Logger = None) -> dict[str, Any]:
         """
-        Issue and return the JWT access and refresh tokens for *account_id*.
+        Issue and return a JWT token pair associated with *account_id*.
 
-        These claims are ignored, if specified in *account_claims*: *iat*, *iss*, *exp*, *jti*, *nbf*, and *sub*.
+        These claims are ignored, if specified in *account_claims*: *iat*, *exp*, *jti*, *nbf*, and *sub*.
         Other claims specified therein may supercede registered account-related claims.
 
         Structure of the return data:
@@ -264,20 +261,19 @@ class JwtRegistry:
         with (self.access_lock):
             account_data: dict[str, Any] = self.__get_account_data(account_id=account_id,
                                                                    logger=logger)
-            current_claims: dict[str, Any] = account_data.get("claims").copy()
+            current_claims: dict[str, Any] = account_data["claims"].copy()
             if account_claims:
                 current_claims.update(account_claims)
             current_claims["jti"] = str_random(size=32,
                                                chars=string.ascii_letters + string.digits)
             current_claims["sub"] = account_id
-            current_claims["iss"] = account_data.get("reference-url")
             errors: list[str] = []
 
             # where is the JWT service provider ?
-            if account_data.get("remote-provider"):
+            if account_data.get("remote-url"):
                 # JWT service is being provided by a remote server
                 result = _jwt_request_token(errors=errors,
-                                            reference_url=current_claims.get("iss"),
+                                            remote_url=account_data.get("remote-url"),
                                             claims=current_claims,
                                             timeout=account_data.get("request-timeout"),
                                             logger=logger)
@@ -371,7 +367,7 @@ class JwtRegistry:
 
 
 def _jwt_request_token(errors: list[str],
-                       reference_url: str,
+                       remote_url: str,
                        claims: dict[str, Any],
                        timeout: int = None,
                        logger: Logger = None) -> dict[str, Any]:
@@ -389,7 +385,7 @@ def _jwt_request_token(errors: list[str],
     of the provider issuing the JWT token.
 
     :param errors: incidental errors
-    :param reference_url: the reference URL for obtaining JWT tokens
+    :param remote_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
@@ -399,9 +395,9 @@ def _jwt_request_token(errors: list[str],
 
     # request the JWT token
     if logger:
-        logger.debug(f"POST request JWT token to '{reference_url}'")
+        logger.debug(f"POST request JWT token to '{remote_url}'")
     response: Response = requests.post(
-        url=reference_url,
+        url=remote_url,
         json=claims,
         timeout=timeout
     )
@@ -414,7 +410,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 to '{reference_url}' failed: {response.reason}"
+        err_msg: str = f"POST request to '{remote_url}' failed: {response.reason}"
         if response.text:
             err_msg += f" - {response.text}"
         if logger: