pypomes-jwt 0.6.9__py3-none-any.whl → 0.7.1__py3-none-any.whl

pypomes_jwt/__init__.py

@@ -1,24 +1,24 @@
-from .jwt_data import (
-    jwt_request_token, jwt_validate_token
+from .jwt_constants import (
+    JWT_DB_ENGINE, JWT_DB_HOST, JWT_DB_NAME,
+    JWT_DB_PORT, JWT_DB_USER, JWT_DB_PWD,
+    JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
+    JWT_ENCODING_KEY, JWT_DECODING_KEY
 )
 from .jwt_pomes import (
-    JWT_ENDPOINT_URL,
-    JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
-    JWT_HS_SECRET_KEY, JWT_RSA_PRIVATE_KEY, JWT_RSA_PUBLIC_KEY,
-    jwt_needed, jwt_verify_request, jwt_claims, jwt_token,
-    jwt_get_token_data, jwt_get_token_claims,
+    jwt_needed, jwt_verify_request, jwt_claims, jwt_tokens,
+    jwt_get_tokens, jwt_get_claims, jwt_validate_token,
     jwt_assert_access, jwt_set_access, jwt_remove_access
 )
 
 __all__ = [
-    # jwt_data
-    "jwt_request_token", "jwt_validate_token",
-    # jwt_pomes
-    "JWT_ENDPOINT_URL",
+    # jwt_constants
+    "JWT_DB_ENGINE", "JWT_DB_HOST", "JWT_DB_NAME",
+    "JWT_DB_PORT", "JWT_DB_USER", "JWT_DB_PWD",
     "JWT_ACCESS_MAX_AGE", "JWT_REFRESH_MAX_AGE",
-    "JWT_HS_SECRET_KEY", "JWT_RSA_PRIVATE_KEY", "JWT_RSA_PUBLIC_KEY",
-    "jwt_needed", "jwt_verify_request", "jwt_claims", "jwt_token",
-    "jwt_get_token_data", "jwt_get_token_claims",
+    "JWT_ENCODING_KEY", "JWT_DECODING_KEY",
+    # jwt_pomes
+    "jwt_needed", "jwt_verify_request", "jwt_claims", "jwt_tokens",
+    "jwt_get_tokens", "jwt_get_claims", "jwt_validate_token",
     "jwt_assert_access", "jwt_set_access", "jwt_remove_access"
 ]
 

pypomes_jwt/jwt_constants.py

@@ -0,0 +1,52 @@
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
+from pypomes_core import (
+    APP_PREFIX,
+    env_get_str, env_get_bytes, env_get_int, env_get_bool
+)
+from secrets import token_bytes
+from typing import Final
+
+# database specs for token persistence
+JWT_DB_ENGINE: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_ENGINE")
+JWT_DB_HOST: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_HOST")
+JWT_DB_NAME: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_NAME")
+JWT_DB_PORT: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_DB_PORT")
+JWT_DB_USER: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_USER")
+JWT_DB_PWD: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DB_PWD")
+
+JWT_ROTATE_TOKENS: Final[bool] = False \
+    if JWT_DB_ENGINE is None else env_get_bool(key=f"{APP_PREFIX}_JWT_ROTATE_TOKENS",
+                                               def_value=False)
+
+# one of HS256, HS512, RSA256, RSA512
+JWT_DEFAULT_ALGORITHM: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DEFAULT_ALGORITHM",
+                                                def_value="HS256")
+# 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)
+# recommended: at least 2 hours (set to 24 hours)
+JWT_REFRESH_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_REFRESH_MAX_AGE",
+                                              def_value=86400)
+
+# recommended: allow the encode and decode keys to be generated anew when app starts
+__encoding_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_ENCODE_KEY")
+__decoding_key: bytes
+if JWT_DEFAULT_ALGORITHM in ["HS256", "HS512"]:
+    if not __encoding_key:
+        __encoding_key = token_bytes(nbytes=32)
+    __decoding_key = __encoding_key
+else:
+    __decoding_key: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_DECODE_KEY")
+    if not __encoding_key or not __decoding_key:
+        __priv_key: RSAPrivateKey = rsa.generate_private_key(public_exponent=65537,
+                                                             key_size=2048)
+        __encoding_key = __priv_key.private_bytes(encoding=serialization.Encoding.PEM,
+                                                  format=serialization.PrivateFormat.PKCS8,
+                                                  encryption_algorithm=serialization.NoEncryption())
+        __pub_key: RSAPublicKey = __priv_key.public_key()
+        __decoding_key = __pub_key.public_bytes(encoding=serialization.Encoding.PEM,
+                                                format=serialization.PublicFormat.SubjectPublicKeyInfo)
+JWT_ENCODING_KEY: Final[bytes] = __encoding_key
+JWT_DECODING_KEY: Final[bytes] = __decoding_key

pypomes_jwt/jwt_data.py

@@ -1,12 +1,16 @@
 import jwt
 import requests
+import string
 from datetime import datetime, timezone
-from jwt.exceptions import InvalidTokenError
 from logging import Logger
 from pypomes_core import str_random
 from requests import Response
 from threading import Lock
-from typing import Any, Literal
+from typing import Any
+
+from .jwt_constants import (
+    JWT_DEFAULT_ALGORITHM, JWT_ENCODING_KEY
+)
 
 
 class JwtData:
@@ -15,171 +19,153 @@ class JwtData:
 
     Instance variables:
         - access_lock: lock for safe multi-threading access
-        - access_data: list with dictionaries holding the JWT token data:
-         [
-           {
-             "control-data": {               # control data
-               "remote-provider": <bool>,    # whether the JWT provider is a remote server
-               "access-token": <jwt-token>,  # access token
-               "algorithm": <string>,        # HS256, HS512, RSA256, RSA512
-               "request-timeout": <int>,     # in seconds - defaults to no timeout
-               "access-max-age": <int>,      # in seconds - defaults to JWT_ACCESS_MAX_AGE
-               "refresh-exp": <timestamp>,   # expiration time for the refresh operation
-               "hs-secret-key": <bytes>,     # HS secret key
-               "rsa-private-key": <bytes>,   # RSA private key
-               "rsa-public-key": <bytes>,    # RSA public key
-             },
-             "reserved-claims": {        # reserved claims
-               "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)
-               # not used:
-               # "aud": <string>         # audience
-               # "nbt": <timestamp>      # not before time
-             },
-             "public-claims": {          # public claims (may be empty)
+        - access_data: list with dictionaries holding the JWT token data, organized by account ids:
+         {
+           <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
+             "token-audience": <string>    # the audience the token is intended for
+             "token_nonce": <string>       # value used to associate a client session with a token
+             "claims": {
                "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
-             },
-             "custom-claims": {          # custom claims (may be empty)
-               "<custom-claim-key-1>": "<custom-claim-value-1>",
+               "roles": <List[str]>,     # subject roles
+               "nonce": <string>,        # value used to associate a Client session with a token
                ...
-               "<custom-claim-key-n>": "<custom-claim-value-n>"
              }
            },
            ...
-         ]
+         }
+
+    JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between
+    two parties. It is fully described in the RFC 7519, issued by the Internet Engineering Task Force
+    (see https://www.rfc-editor.org/rfc/rfc7519.html).
+    In this context, claims are pieces of information a token bears, and herein are loosely classified
+    as token-related and account-related. All times are UTC.
+
+    Token-related claims are mostly required claims, and convey information about the token itself:
+       "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)
+       "nat": <string>           # nature of token (A: access; R: refresh) - locally issued tokens, only
+       # optional:
+       "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:
+       "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>         # value used to associate a client session with a token
     """
     def __init__(self) -> None:
         """
         Initizalize the token access data.
         """
         self.access_lock: Lock = Lock()
-        self.access_data: list[dict[str, dict[str, Any]]] = []
-
-    def add_access_data(self,
-                        account_id: str,
-                        reference_url: str,
-                        claims: dict[str, Any],
-                        algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"],
-                        access_max_age: int,
-                        refresh_max_age: int,
-                        hs_secret_key: bytes,
-                        rsa_private_key: bytes,
-                        rsa_public_key: bytes,
-                        request_timeout: int,
-                        remote_provider: bool,
-                        logger: Logger = None) -> None:
+        self.access_data: dict[str, Any] = {}
+
+    def add_access(self,
+                   account_id: str,
+                   reference_url: str,
+                   claims: dict[str, Any],
+                   access_max_age: int,
+                   refresh_max_age: int,
+                   grace_interval: int,
+                   token_audience: str,
+                   token_nonce: str,
+                   request_timeout: int,
+                   remote_provider: bool,
+                   logger: Logger = None) -> None:
         """
         Add to storage the parameters needed to produce and validate JWT tokens for *account_id*.
 
-        The parameter *claims* may contain public and custom claims. Currently, the public claims supported
-        are *birthdate*, *email*, *gender*, *name*, and *roles*. Everything else is considered to be custom
-        claims, and sent to the remote JWT provided, if applicable.
-
-        Presently, the *refresh_max_age* data is not relevant, as the authorization parameters in *claims*
-        (typically, an acess-key/hs-secret-key pair), have been previously validated elsewhere.
-        This situation might change in the future.
+        The parameter *claims* may contain account-related claims, only. Ideally, it should contain,
+        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.
 
         :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 algorithm: the algorithm used to sign the token with
-        :param access_max_age: token duration (in seconds)
-        :param refresh_max_age: duration for the refresh operation (in seconds)
-        :param hs_secret_key: secret key for HS authentication
-        :param rsa_private_key: private key for RSA authentication
-        :param rsa_public_key: public key for RSA authentication
+        :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 token_audience: the audience the token is intended for
+        :param token_nonce: optional value used to associate a client session with a token
         :param request_timeout: timeout for the requests to the reference URL
         :param remote_provider: whether the JWT provider is a remote server
         :param logger: optional logger
         """
-        # Do the access data already exist ?
-        if not self.get_access_data(account_id=account_id):
-            # no, build control data
-            control_data: dict[str, Any] = {
-                "algorithm": algorithm,
-                "access-max-age": access_max_age,
-                "request-timeout": request_timeout,
-                "remote-provider": remote_provider,
-                "refresh-exp": int(datetime.now(tz=timezone.utc).timestamp()) + refresh_max_age
-            }
-            if algorithm in ["HS256", "HS512"]:
-                control_data["hs-secret-key"] = hs_secret_key
-            else:
-                control_data["rsa-private-key"] = rsa_private_key
-                control_data["rsa-public-key"] = rsa_public_key
-
-            # build claims
-            reserved_claims: dict[str, Any] = {
-                "sub": account_id,
-                "iss": reference_url,
-                "exp": 0,
-                "iat": 0,
-                "jti": "<jwt-id>",
-            }
-            custom_claims: dict[str, Any] = {}
-            public_claims: dict[str, Any] = {}
-            for key, value in claims.items():
-                if key in ["birthdate", "email", "gender", "name", "roles"]:
-                    public_claims[key] = value
-                else:
-                    custom_claims[key] = value
-            # store access data
-            item_data = {
-                "control-data": control_data,
-                "reserved-claims": reserved_claims,
-                "public-claims": public_claims,
-                "custom-claims": custom_claims
-            }
-            with self.access_lock:
-                self.access_data.append(item_data)
-            if logger:
-                logger.debug(f"JWT data added for '{account_id}': {item_data}")
-        elif logger:
-            logger.warning(f"JWT data already exists for '{account_id}'")
-
-    def remove_access_data(self,
-                           account_id: str,
-                           logger: Logger) -> None:
+        # 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,
+                    "token-audience": token_audience,
+                    "token-nonce": token_nonce,
+                    "request-timeout": request_timeout,
+                    "remote-provider": remote_provider,
+                    "claims": claims or {}
+                }
+                if logger:
+                    logger.debug(f"JWT data added for '{account_id}'")
+            elif logger:
+                logger.warning(f"JWT data already exists for '{account_id}'")
+
+    def remove_access(self,
+                      account_id: str,
+                      logger: Logger) -> bool:
         """
         Remove from storage the access data for *account_id*.
 
         :param account_id: the account identification
         :param logger: optional logger
+        return: *True* if the access data was removed, *False* otherwise
         """
-        # obtain the access data item in storage
-        item_data: dict[str, dict[str, Any]] = self.get_access_data(account_id=account_id,
-                                                                    logger=logger)
-        if item_data:
-            with self.access_lock:
-                self.access_data.remove(item_data)
-            if logger:
+        account_data: dict[str, Any] | None
+        with self.access_lock:
+            account_data = self.access_data.pop(account_id, None)
+
+        if logger:
+            if account_data:
                 logger.debug(f"Removed JWT data for '{account_id}'")
-        elif logger:
-            logger.warning(f"No JWT data found for '{account_id}'")
+            else:
+                logger.warning(f"No JWT data found for '{account_id}'")
 
-    def get_token_data(self,
-                       account_id: str,
-                       superceding_claims: dict[str, Any] = None,
-                       logger: Logger = None) -> dict[str, Any]:
+        return account_data is not None
+
+    def issue_tokens(self,
+                     account_id: str,
+                     account_claims: dict[str, Any] = None,
+                     logger: Logger = None) -> dict[str, Any]:
         """
-        Obtain and return the JWT token for *account_id*, along with its duration.
+        Issue and return the JWT access and refresh tokens for *account_id*.
 
         Structure of the return data:
         {
           "access_token": <jwt-token>,
           "created_in": <timestamp>,
-          "expires_in": <seconds-to-expiration>
+          "expires_in": <seconds-to-expiration>,
+          "refresh_token": <jwt-token>
         }
 
         :param account_id: the account identification
-        :param superceding_claims: if provided, may supercede registered custom claims
+        :param account_claims: if provided, may supercede registered account-related claims
         :param logger: optional logger
         :return: the JWT token data, or *None* if error
         :raises InvalidTokenError: token is invalid
@@ -195,28 +181,27 @@ class JwtData:
         :raises RuntimeError: access data not found for the given *account_id*, or
                               the remote JWT provider failed to return a token
         """
-        # declare the return variable
-        result: dict[str, Any]
+        # initialize the return variable
+        result: dict[str, Any] | None = None
+
+        # process the data in storage
+        with (self.access_lock):
+            account_data: dict[str, Any] = self.access_data.get(account_id)
 
-        # obtain the item in storage
-        access_data: dict[str, Any] = self.get_access_data(account_id=account_id,
-                                                           logger=logger)
-        # was the JWT data obtained ?
-        if access_data:
-            # yes, proceed
-            control_data: dict[str, Any] = access_data.get("control-data")
-            reserved_claims: dict[str, Any] = access_data.get("reserved-claims")
-            custom_claims: dict[str, Any] = access_data.get("custom-claims")
-            if superceding_claims:
-                custom_claims = custom_claims.copy()
-                custom_claims.update(superceding_claims)
+            # was the JWT data obtained ?
+            if account_data:
+                # yes, proceed
+                current_claims: dict[str, Any] = account_data.get("claims").copy()
+                if account_claims:
+                    current_claims.update(current_claims)
+
+                # obtain new tokens
+                current_claims["jti"] = str_random(size=32,
+                                                   chars=string.ascii_letters + string.digits)
+                current_claims["iss"] = account_data.get("reference-url")
 
-            # obtain a new token, if the current token has expired
-            just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
-            if just_now > reserved_claims.get("exp"):
-                token_jti: str = str_random(size=16)
                 # where is the JWT service provider ?
-                if control_data.get("remote-provider"):
+                if account_data.get("remote-provider"):
                     # JWT service is being provided by a remote server
                     errors: list[str] = []
                     # Structure of the return data:
@@ -224,138 +209,53 @@ class JwtData:
                     #   "access_token": <jwt-token>,
                     #   "created_in": <timestamp>,
                     #   "expires_in": <seconds-to-expiration>,
+                    #   "refresh_token": <jwt-token>
                     #   ...
                     # }
-                    reply: dict[str, Any] = jwt_request_token(errors=errors,
-                                                              reference_url=reserved_claims.get("iss"),
-                                                              claims=custom_claims,
-                                                              timeout=control_data.get("request-timeout"),
-                                                              logger=logger)
-                    if reply:
-                        with self.access_lock:
-                            control_data["access-token"] = reply.get("access_token")
-                            reserved_claims["jti"] = token_jti
-                            reserved_claims["iat"] = reply.get("created_in")
-                            reserved_claims["exp"] = reply.get("created_in") + reply.get("expires_in")
-                    else:
+                    result = _jwt_request_token(errors=errors,
+                                                reference_url=current_claims.get("iss"),
+                                                claims=current_claims,
+                                                timeout=account_data.get("request-timeout"),
+                                                logger=logger)
+                    if errors:
                         raise RuntimeError(" - ".join(errors))
                 else:
                     # JWT service is being provided locally
-                    token_iat: int = just_now
-                    token_exp: int = just_now + control_data.get("access-max-age")
-                    claims: dict[str, Any] = access_data.get("public-claims").copy()
-                    claims.update(reserved_claims)
-                    claims.update(custom_claims)
-                    claims["jti"] = token_jti
-                    claims["iat"] = token_iat
-                    claims["exp"] = token_exp
+                    just_now: float = datetime.now(tz=timezone.utc).timestamp()
+                    current_claims["iat"] = just_now
+                    current_claims["exp"] = just_now + account_data.get("access-max-age")
+                    current_claims["nat"] = "R"
                     # may raise an exception
-                    token: str = jwt.encode(payload=claims,
-                                            key=(control_data.get("hs-secret-key") or
-                                                 control_data.get("rsa-private-key")),
-                                            algorithm=control_data.get("algorithm"))
-                    with self.access_lock:
-                        reserved_claims["jti"] = token_jti
-                        reserved_claims["iat"] = token_iat
-                        reserved_claims["exp"] = token_exp
-                        control_data["access-token"] = token
-
-            # return the token
-            result = {
-                "access_token": control_data.get("access-token"),
-                "created_in": reserved_claims.get("iat"),
-                "expires_in": reserved_claims.get("exp") - reserved_claims.get("iat")
-            }
-        else:
-            # JWT access data not found
-            err_msg: str = f"No JWT access data found for '{account_id}'"
-            if logger:
-                logger.error(err_msg)
-            raise RuntimeError(err_msg)
-
-        return result
-
-    def get_token_claims(self,
-                         token: str,
-                         logger: Logger = None) -> dict[str, Any]:
-        """
-        Obtain and return the claims of a JWT *token*.
-
-        :param token: the token to be inspected for claims
-        :param logger: optional logger
-        :return: the token's claimset, or *None* if error
-        :raises InvalidTokenError: token is not valid
-        :raises ExpiredSignatureError: token has expired
-        :raises InvalidAlgorithmError: the specified algorithm is not recognized
-        """
-        # declare the return variable
-        result: dict[str, Any]
-
-        if logger:
-            logger.debug(msg=f"Retrieve claims for JWT token '{token}'")
-
-        access_data: dict[str, Any] = self.get_access_data(access_token=token,
-                                                           logger=logger)
-        if access_data:
-            control_data: dict[str, Any] = access_data.get("control-data")
-            if control_data.get("remote-provider"):
-                # provider is remote
-                result = control_data.get("custom-claims")
+                    refresh_token: str = jwt.encode(payload=current_claims,
+                                                    key=JWT_ENCODING_KEY,
+                                                    algorithm=JWT_DEFAULT_ALGORITHM)
+                    current_claims["nat"] = "A"
+                    # 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,
+                        "created_in": account_claims.get("iat"),
+                        "expires_in": account_claims.get("exp"),
+                        "refresh_token": refresh_token
+                    }
             else:
-                # may raise an exception
-                result = jwt.decode(jwt=token,
-                                    key=(control_data.get("hs-secret-key") or
-                                         control_data.get("rsa-public-key")),
-                                    algorithms=[control_data.get("algorithm")])
-        else:
-            raise InvalidTokenError("JWT token is not valid")
-
-        if logger:
-            logger.debug(f"Retrieved claims for JWT token '{token}': {result}")
+                # JWT access data not found
+                err_msg: str = f"No JWT access data found for '{account_id}'"
+                if logger:
+                    logger.error(err_msg)
+                raise RuntimeError(err_msg)
 
         return result
 
-    def get_access_data(self,
-                        account_id: str = None,
-                        access_token: str = None,
-                        logger: Logger = None) -> dict[str, dict[str, Any]]:
-        # noinspection HttpUrlsUsage
-        """
-        Retrieve and return the access data in storage for *account_id*, or optionally, for *access_token*.
-
-        Either *account_id* or *access_token* must be provided, the former having precedence over the later.
-        Note that, whereas *account_id* uniquely identifies an access dataset, *access_token* might not,
-        and thus, the first dataset associated with it would be returned.
-
-        :param account_id: the account identification
-        :param access_token: the access token
-        :param logger: optional logger
-        :return: the corresponding item in storage, or *None* if not found
-        """
-        # initialize the return variable
-        result: dict[str, dict[str, Any]] | None = None
-    
-        if logger:
-            target: str = f"account id '{account_id}'" if account_id else f"token '{access_token}'"
-            logger.debug(f"Retrieve access data for {target}")
-        # retrieve the data
-        with self.access_lock:
-            for item_data in self.access_data:
-                if (account_id and account_id == item_data.get("reserved-claims").get("sub")) or \
-                        (access_token and access_token == item_data.get("control-data").get("access-token")):
-                    result = item_data
-                    break
-        if logger:
-            logger.debug(f"Data is '{result}'")
 
-        return result
-
-
-def jwt_request_token(errors: list[str],
-                      reference_url: str,
-                      claims: dict[str, Any],
-                      timeout: int = None,
-                      logger: Logger = None) -> dict[str, Any]:
+def _jwt_request_token(errors: list[str],
+                       reference_url: str,
+                       claims: dict[str, Any],
+                       timeout: int = None,
+                       logger: Logger = None) -> dict[str, Any]:
     """
     Obtain and return the JWT token from *reference_url*, along with its duration.
 
@@ -401,30 +301,3 @@ def jwt_request_token(errors: list[str],
         errors.append(err_msg)
 
     return result
-
-
-def jwt_validate_token(token: str,
-                       key: bytes | str,
-                       algorithm: str,
-                       logger: Logger = None) -> None:
-    """
-    Verify if *token* ia a valid JWT token.
-
-    Raise an appropriate exception if validation failed.
-
-    :param token: the token to be validated
-    :param key: the secret or public key used to create the token (HS or RSA authentication, respectively)
-    :param algorithm: the algorithm used to to sign the token with
-    :param logger: optional logger
-    :raises InvalidTokenError: token is invalid
-    :raises InvalidKeyError: authentication key is not in the proper format
-    :raises ExpiredSignatureError: token and refresh period have expired
-    :raises InvalidSignatureError: signature does not match the one provided as part of the token
-    """
-    if logger:
-        logger.debug(msg=f"Validate JWT token '{token}'")
-    jwt.decode(jwt=token,
-               key=key,
-               algorithms=[algorithm])
-    if logger:
-        logger.debug(msg=f"Token '{token}' is valid")

pypomes_jwt/jwt_pomes.py

@@ -1,40 +1,14 @@
 import contextlib
-from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.asymmetric import rsa
-from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
-from datetime import datetime
+import jwt
 from flask import Request, Response, request, jsonify
 from logging import Logger
-from pypomes_core import APP_PREFIX, env_get_str, env_get_bytes, env_get_int
-from secrets import token_bytes
-from typing import Any, Final, Literal
-
-from .jwt_data import JwtData, jwt_validate_token
-
-JWT_DEFAULT_ALGORITHM: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_DEFAULT_ALGORITHM",
-                                                def_value="HS256")
-JWT_ACCESS_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_ACCESS_MAX_AGE",
-                                             def_value=3600)
-JWT_REFRESH_MAX_AGE: Final[int] = env_get_int(key=f"{APP_PREFIX}_JWT_REFRESH_MAX_AGE",
-                                              def_value=43200)
-JWT_HS_SECRET_KEY: Final[bytes] = env_get_bytes(key=f"{APP_PREFIX}_JWT_HS_SECRET_KEY",
-                                                def_value=token_bytes(nbytes=32))
-JWT_ENDPOINT_URL: Final[str] = env_get_str(key=f"{APP_PREFIX}_JWT_ENDPOINT_URL")
-
-# obtain a RSA private/public key pair
-__priv_bytes: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PRIVATE_KEY")
-__pub_bytes: bytes = env_get_bytes(key=f"{APP_PREFIX}_JWT_RSA_PUBLIC_KEY")
-if not __priv_bytes or not __pub_bytes:
-    __priv_key: RSAPrivateKey = rsa.generate_private_key(public_exponent=65537,
-                                                         key_size=2048)
-    __priv_bytes = __priv_key.private_bytes(encoding=serialization.Encoding.PEM,
-                                            format=serialization.PrivateFormat.PKCS8,
-                                            encryption_algorithm=serialization.NoEncryption())
-    __pub_key: RSAPublicKey = __priv_key.public_key()
-    __pub_bytes = __pub_key.public_bytes(encoding=serialization.Encoding.PEM,
-                                         format=serialization.PublicFormat.SubjectPublicKeyInfo)
-JWT_RSA_PRIVATE_KEY: Final[bytes] = __priv_bytes
-JWT_RSA_PUBLIC_KEY: Final[bytes] = __pub_bytes
+from typing import Any, Literal
+
+from .jwt_constants import (
+    JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
+    JWT_DEFAULT_ALGORITHM, JWT_DECODING_KEY
+)
+from .jwt_data import JwtData
 
 # the JWT data object
 __jwt_data: JwtData = JwtData()
@@ -59,23 +33,22 @@ def jwt_needed(func: callable) -> callable:
 
 def jwt_assert_access(account_id: str) -> bool:
     """
-    Determine whether access for *ccount_id* has been established.
+    Determine whether access for *account_id* has been established.
 
     :param account_id: the account identification
     :return: *True* if access data exists for *account_id*, *False* otherwise
     """
-    return __jwt_data.get_access_data(account_id=account_id) is not None
+    return __jwt_data.access_data.get(account_id) is not None
 
 
 def jwt_set_access(account_id: str,
                    reference_url: str,
                    claims: dict[str, Any],
-                   algorithm: Literal["HS256", "HS512", "RSA256", "RSA512"] = JWT_DEFAULT_ALGORITHM,
                    access_max_age: int = JWT_ACCESS_MAX_AGE,
                    refresh_max_age: int = JWT_REFRESH_MAX_AGE,
-                   secret_key: bytes = JWT_HS_SECRET_KEY,
-                   private_key: bytes = JWT_RSA_PRIVATE_KEY,
-                   public_key: bytes = JWT_RSA_PUBLIC_KEY,
+                   grace_interval: int = None,
+                   token_audience: str = None,
+                   token_nonce: str = None,
                    request_timeout: int = None,
                    remote_provider: bool = True,
                    logger: Logger = None) -> None:
@@ -85,12 +58,11 @@ def jwt_set_access(account_id: str,
     :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 algorithm: the authentication type
-    :param access_max_age: token duration, in seconds
-    :param refresh_max_age: duration for the refresh operation, in seconds
-    :param secret_key: secret key for HS authentication
-    :param private_key: private key for RSA authentication
-    :param public_key: public key for RSA authentication
+    :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 token_audience: optional audience the token is intended for
+    :param token_nonce: optional value used to associate a client session with a token
     :param request_timeout: timeout for the requests to the reference URL
     :param remote_provider: whether the JWT provider is a remote server
     :param logger: optional logger
@@ -107,52 +79,98 @@ def jwt_set_access(account_id: str,
         reference_url = reference_url[:pos]
 
     # register the JWT service
-    __jwt_data.add_access_data(account_id=account_id,
-                               reference_url=reference_url,
-                               claims=claims,
-                               algorithm=algorithm,
-                               access_max_age=access_max_age,
-                               refresh_max_age=refresh_max_age,
-                               hs_secret_key=secret_key,
-                               rsa_private_key=private_key,
-                               rsa_public_key=public_key,
-                               request_timeout=request_timeout,
-                               remote_provider=remote_provider,
-                               logger=logger)
+    __jwt_data.add_access(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,
+                          token_audience=token_audience,
+                          token_nonce=token_nonce,
+                          request_timeout=request_timeout,
+                          remote_provider=remote_provider,
+                          logger=logger)
 
 
 def jwt_remove_access(account_id: str,
-                      logger: Logger = None) -> None:
+                      logger: Logger = None) -> bool:
     """
     Remove from storage the JWT access data for *account_id*.
 
     :param account_id: the account identification
     :param logger: optional logger
+    return: *True* if the access data was removed, *False* otherwise
     """
     if logger:
         logger.debug(msg=f"Remove access data for '{account_id}'")
 
-    __jwt_data.remove_access_data(account_id=account_id,
-                                  logger=logger)
+    return __jwt_data.remove_access(account_id=account_id,
+                                    logger=logger)
 
 
-def jwt_get_token_data(errors: list[str],
-                       account_id: str,
-                       superceding_claims: dict[str, Any] = None,
-                       logger: Logger = None) -> dict[str, Any]:
+def jwt_validate_token(errors: list[str] | None,
+                       token: str,
+                       nature: Literal["A", "R"] = None,
+                       logger: Logger = None) -> bool:
     """
-    Obtain and return the JWT token data associated with *account_id*.
+    Verify if *token* ia a valid JWT token.
+
+    Raise an appropriate exception if validation failed.
+
+    :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 logger: optional logger
+    :return: *True* if token is valid, *False* otherwise
+    """
+    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 "nat" in claims and nature != claims.get("nat"):
+            nat: str = "an access" if nature == "A" else "a refresh"
+            err_msg = f"Token is not {nat} token"
+    except Exception as e:
+        err_msg = str(e)
+
+    if err_msg:
+        if logger:
+            logger.error(msg=err_msg)
+        if isinstance(errors, list):
+            errors.append(err_msg)
+    elif logger:
+        logger.debug(msg=f"Token '{token}' is valid")
+
+    return err_msg is None
+
+
+def jwt_get_tokens(errors: list[str] | None,
+                   account_id: str,
+                   account_claims: dict[str, Any] = None,
+                   logger: Logger = None) -> dict[str, Any]:
+    """
+    Issue and return the JWT token data associated with *account_id*.
 
     Structure of the return data:
     {
       "access_token": <jwt-token>,
       "created_in": <timestamp>,
-      "expires_in": <seconds-to-expiration>
+      "expires_in": <seconds-to-expiration>,
+      "refresh_token": <jwt-token>
     }
 
     :param errors: incidental error messages
     :param account_id: the account identification
-    :param superceding_claims: if provided, may supercede registered custom claims
+    :param account_claims: if provided, may supercede registered custom claims
     :param logger: optional logger
     :return: the JWT token data, or *None* if error
     """
@@ -162,22 +180,23 @@ def jwt_get_token_data(errors: list[str],
     if logger:
         logger.debug(msg=f"Retrieve JWT token data for '{account_id}'")
     try:
-        result = __jwt_data.get_token_data(account_id=account_id,
-                                           superceding_claims=superceding_claims,
-                                           logger=logger)
+        result = __jwt_data.issue_tokens(account_id=account_id,
+                                         account_claims=account_claims,
+                                         logger=logger)
         if logger:
             logger.debug(msg=f"Data is '{result}'")
     except Exception as e:
         if logger:
             logger.error(msg=str(e))
-        errors.append(str(e))
+        if isinstance(errors, list):
+            errors.append(str(e))
 
     return result
 
 
-def jwt_get_token_claims(errors: list[str],
-                         token: str,
-                         logger: Logger = None) -> dict[str, Any]:
+def jwt_get_claims(errors: list[str] | None,
+                   token: str,
+                   logger: Logger = None) -> dict[str, Any]:
     """
     Obtain and return the claims set of a JWT *token*.
 
@@ -193,11 +212,19 @@ def jwt_get_token_claims(errors: list[str],
         logger.debug(msg=f"Retrieve claims for token '{token}'")
 
     try:
-        result = __jwt_data.get_token_claims(token=token)
+        reply: dict[str, Any] = jwt.decode(jwt=token,
+                                           options={"verify_signature": False})
+        if reply.get("nat") in ["A", "R"]:
+            result = jwt.decode(jwt=token,
+                                key=JWT_DECODING_KEY,
+                                algorithms=[JWT_DEFAULT_ALGORITHM])
+        else:
+            result = reply
     except Exception as e:
         if logger:
             logger.error(msg=str(e))
-        errors.append(str(e))
+        if isinstance(errors, list):
+            errors.append(str(e))
 
     return result
 
@@ -227,26 +254,11 @@ def jwt_verify_request(request: Request,
         token: str = auth_header.split(" ")[1]
         if logger:
             logger.debug(msg=f"Token is '{token}'")
-        # retrieve the reference access data
-        access_data: dict[str, Any] = __jwt_data.get_access_data(access_token=token)
-        if access_data:
-            control_data: dict[str, Any] = access_data.get("control-data")
-            if control_data.get("remote-provider"):
-                # JWT provider is remote
-                if datetime.now().timestamp() > access_data.get("reserved-claims").get("exp"):
-                    err_msg = "Token has expired"
-            else:
-                # JWT was locally provided
-                try:
-                    jwt_validate_token(token=token,
-                                       key=(control_data.get("hs-secret-key") or
-                                            control_data.get("rsa-public-key")),
-                                       algorithm=control_data.get("algorithm"))
-                except Exception as e:
-                    # validation failed
-                    err_msg = str(e)
-        else:
-            err_msg = "No access data found for token"
+        errors: list[str] = []
+        jwt_validate_token(errors=errors,
+                           token=token)
+        if errors:
+            err_msg = "; ".join(errors)
     else:
         # no 'Bearer' found, report the error
         err_msg = "Request header has no 'Bearer' data"
@@ -289,13 +301,14 @@ def jwt_claims(token: str = None) -> Response:
     # has the token been obtained ?
     if token:
         # yes, obtain the token data
-        try:
-            token_claims: dict[str, Any] = __jwt_data.get_token_claims(token=token)
-            result = jsonify(token_claims)
-        except Exception as e:
-            # claims extraction failed
-            result = Response(response=str(e),
+        errors: list[str] = []
+        token_claims: dict[str, Any] = jwt_get_claims(errors=errors,
+                                                      token=token)
+        if errors:
+            result = Response(response=errors,
                               status=400)
+        else:
+            result = jsonify(token_claims)
     else:
         # no, report the problem
         result = Response(response="Invalid parameters",
@@ -304,26 +317,28 @@ def jwt_claims(token: str = None) -> Response:
     return result
 
 
-def jwt_token(service_params: dict[str, Any] = None) -> Response:
+def jwt_tokens(service_params: dict[str, Any] = None) -> Response:
     """
-    REST service entry point for obtaining JWT tokens.
+    REST service entry point for obtaining or refreshing JWT tokens.
 
     The requester must send, as parameter *service_params* or in the body of the request:
     {
-      "account-id": "<string>"                              - required account identification
-      "<custom-claim-key-1>": "<custom-claim-value-1>",     - optional superceding custom claims
+      "account-id": "<string>"                             - required account identification
+      "refresh_token": <string>                            - if refresh is being requested
+      "<account-claim-key-1>": "<account-claim-value-1>",  - optional superceding account claims
       ...
-      "<custom-claim-key-n>": "<custom-claim-value-n>"
+      "<account-claim-key-n>": "<account-claim-value-n>"
     }
-    If provided, the superceding custom claims will be sent to the remote provider, if applicable
-    (custom claims currently registered for the account may be overridden).
-
+    if provided, the refresh token will cause a token refresh operation to be carried out.
+    Otherwise, a regular token issue operation is carried out, with the optional superceding
+    account claims being used (claims currently registered for the account may be overridden).
 
     Structure of the return data:
     {
       "access_token": <jwt-token>,
       "created_in": <timestamp>,
-      "expires_in": <seconds-to-expiration>
+      "expires_in": <seconds-to-expiration>,
+      "refresh_token": <jwt-token>
     }
 
     :param service_params: the optional JSON containing the request parameters (defaults to JSON in body)
@@ -339,21 +354,39 @@ def jwt_token(service_params: dict[str, Any] = None) -> Response:
         with contextlib.suppress(Exception):
             params = request.get_json()
     account_id: str | None = params.pop("account-id", None)
+    refresh_token: str | None = params.pop("refresh-token", None)
+    err_msg: str | None = None
+    token_data: dict[str, Any] | None = None
 
     # has the account been identified ?
     if account_id:
-        # yes, obtain the token data
-        try:
-            token_data: dict[str, Any] = __jwt_data.get_token_data(account_id=account_id,
-                                                                   superceding_claims=params)
-            result = jsonify(token_data)
-        except Exception as e:
-            # token validation failed
-            result = Response(response=str(e),
-                              status=401)
+        # yes, proceed
+        if refresh_token:
+            errors: list[str] = []
+            claims: dict[str, Any] = jwt_get_claims(errors=errors,
+                                                    token=refresh_token)
+            if errors:
+                err_msg = "; ".join(errors)
+            elif claims.get("nat") != "R":
+                err_msg = "Invalid parameters"
+            else:
+                params = claims
+
+        if not err_msg:
+            try:
+                token_data = __jwt_data.issue_tokens(account_id=account_id,
+                                                     account_claims=params)
+            except Exception as e:
+                # token issuing failed
+                err_msg = str(e)
     else:
         # no, report the problem
-        result = Response(response="Invalid parameters",
+        err_msg = "Invalid parameters"
+
+    if err_msg:
+        result = Response(response=err_msg,
                           status=401)
+    else:
+        result = jsonify(token_data)
 
     return result

{pypomes_jwt-0.6.9.dist-info → pypomes_jwt-0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.6.9
+Version: 0.7.1
 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
@@ -10,6 +10,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
-Requires-Dist: cryptography>=44.0.1
+Requires-Dist: cryptography>=44.0.2
 Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: pypomes-core>=1.7.9
+Requires-Dist: pypomes-core>=1.8.3

pypomes_jwt-0.7.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+pypomes_jwt/__init__.py,sha256=4dBUGZTw1c-TeZukYjwAM7VWFzoFBSEyAN26jgjQRtM,1022
+pypomes_jwt/jwt_constants.py,sha256=k1PFqBF7KI2Ie8ErOW1zw9IWTgqjkxvU4m2eKGr_1EA,2927
+pypomes_jwt/jwt_data.py,sha256=npKZqHZbftvvOGCRAl-2yovUbqCQW0FvcQvyuYGXA_U,14189
+pypomes_jwt/jwt_pomes.py,sha256=w2sgJUF4CZibBCxU_-PZvrQyMm1saP0FBnf1yCCUSak,14247
+pypomes_jwt-0.7.1.dist-info/METADATA,sha256=S092HRvlJYZVEgHbzJyZ3o1bAqlIqUwEri37srho9jA,599
+pypomes_jwt-0.7.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pypomes_jwt-0.7.1.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
+pypomes_jwt-0.7.1.dist-info/RECORD,,

pypomes_jwt-0.6.9.dist-info/RECORD

@@ -1,7 +0,0 @@
-pypomes_jwt/__init__.py,sha256=CwpFtZEi1Yo1i4ulyR65yvo_fJpSRMJsXwzV75E3K0A,988
-pypomes_jwt/jwt_data.py,sha256=o89rMzaUp3-GpX3zei2UkFzYacyjmMvi2QPq1vBaNGY,19945
-pypomes_jwt/jwt_pomes.py,sha256=rhYoqD57yXayJoePdjbB3RfPAIg23o6YQKkdnD4tz0c,14222
-pypomes_jwt-0.6.9.dist-info/METADATA,sha256=penqUj2BH3vbm9Br2kOv15Gcj5fkBj6Jx6tug_bbYxY,599
-pypomes_jwt-0.6.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pypomes_jwt-0.6.9.dist-info/licenses/LICENSE,sha256=NdakochSXm_H_-DSL_x2JlRCkYikj3snYYvTwgR5d_c,1086
-pypomes_jwt-0.6.9.dist-info/RECORD,,