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

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

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

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

{pypomes_jwt-0.9.0 → pypomes_jwt-0.9.2}/src/pypomes_jwt/__init__.py

@@ -3,13 +3,14 @@ from .jwt_constants import (
     JWT_DB_PORT, JWT_DB_USER, JWT_DB_PWD,
     JWT_DB_TABLE, JWT_DB_COL_KID, JWT_DB_COL_ACCOUNT,
     JWT_DB_COL_ALGORITHM, JWT_DB_COL_DECODER, JWT_DB_COL_TOKEN,
-    JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE,
-    JWT_ENCODING_KEY, JWT_DECODING_KEY
+    JWT_ACCOUNT_LIMIT, JWT_ENCODING_KEY, JWT_DECODING_KEY,
+    JWT_ACCESS_MAX_AGE, JWT_REFRESH_MAX_AGE
 )
 from .jwt_pomes import (
     jwt_needed, jwt_verify_request,
     jwt_assert_account, jwt_set_account, jwt_remove_account,
-    jwt_get_tokens, jwt_get_claims, jwt_validate_token, jwt_revoke_token
+    jwt_issue_token, jwt_issue_tokens, jwt_get_claims,
+    jwt_validate_token, jwt_revoke_token
 )
 
 __all__ = [
@@ -18,12 +19,13 @@ __all__ = [
     "JWT_DB_PORT", "JWT_DB_USER", "JWT_DB_PWD",
     "JWT_DB_TABLE", "JWT_DB_COL_KID", "JWT_DB_COL_ACCOUNT",
     "JWT_DB_COL_ALGORITHM", "JWT_DB_COL_DECODER", "JWT_DB_COL_TOKEN",
+    "JWT_ACCOUNT_LIMIT", "JWT_ENCODING_KEY", "JWT_DECODING_KEY",
     "JWT_ACCESS_MAX_AGE", "JWT_REFRESH_MAX_AGE",
-    "JWT_ENCODING_KEY", "JWT_DECODING_KEY",
     # jwt_pomes
     "jwt_needed", "jwt_verify_request",
     "jwt_assert_account", "jwt_set_account", "jwt_remove_account",
-    "jwt_get_tokens", "jwt_get_claims", "jwt_validate_token", "jwt_revoke_token"
+    "jwt_issue_token", "jwt_issue_tokens", "jwt_get_claims",
+    "jwt_validate_token", "jwt_revoke_token"
 ]
 
 from importlib.metadata import version

{pypomes_jwt-0.9.0 → pypomes_jwt-0.9.2}/src/pypomes_jwt/jwt_pomes.py

@@ -11,10 +11,10 @@ from .jwt_constants import (
     JWT_DEFAULT_ALGORITHM, JWT_DECODING_KEY,
     JWT_DB_TABLE, JWT_DB_COL_KID, JWT_DB_COL_ALGORITHM, JWT_DB_COL_DECODER
 )
-from .jwt_data import JwtData
+from .jwt_registry import JwtRegistry
 
 # the JWT data object
-__jwt_data: JwtData = JwtData()
+__jwt_registry: JwtRegistry = JwtRegistry()
 
 
 def jwt_needed(func: callable) -> callable:
@@ -58,10 +58,10 @@ def jwt_verify_request(request: Request,
         # yes, extract and validate the JWT access token
         token: str = auth_header.split(" ")[1]
         if logger:
-            logger.debug(msg="Token was found")
+            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)
@@ -85,7 +85,7 @@ def jwt_assert_account(account_id: str) -> bool:
     :param account_id: the account identification
     :return: *True* if access data exists for *account_id*, *False* otherwise
     """
-    return __jwt_data.access_data.get(account_id) is not None
+    return __jwt_registry.access_data.get(account_id) is not None
 
 
 def jwt_set_account(account_id: str,
@@ -126,17 +126,17 @@ def jwt_set_account(account_id: str,
         reference_url = reference_url[:pos]
 
     # register the JWT service
-    __jwt_data.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,
-                           token_audience=token_audience,
-                           token_nonce=token_nonce,
-                           request_timeout=request_timeout,
-                           remote_provider=remote_provider,
-                           logger=logger)
+    __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,
+                               token_audience=token_audience,
+                               token_nonce=token_nonce,
+                               request_timeout=request_timeout,
+                               remote_provider=remote_provider,
+                               logger=logger)
 
 
 def jwt_remove_account(account_id: str,
@@ -151,26 +151,26 @@ def jwt_remove_account(account_id: str,
     if logger:
         logger.debug(msg=f"Remove access data for '{account_id}'")
 
-    return __jwt_data.remove_account(account_id=account_id,
-                                     logger=logger)
+    return __jwt_registry.remove_account(account_id=account_id,
+                                         logger=logger)
 
 
 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,9 +188,10 @@ 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:
+    elif token_kid and len(token_kid) > 1 and token_kid[0:1].isupper() 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:
             where_data[JWT_DB_COL_ACCOUNT] = account_id
@@ -275,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:
@@ -298,16 +299,71 @@ def jwt_revoke_token(errors: list[str] | None,
     return result
 
 
-def jwt_get_tokens(errors: list[str] | None,
-                   account_id: str,
-                   account_claims: dict[str, Any] = None,
-                   refresh_token: str = None,
-                   logger: Logger = None) -> dict[str, Any]:
+def jwt_issue_token(errors: list[str] | None,
+                    account_id: str,
+                    nature: str,
+                    duration: int,
+                    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 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).
+    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, 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: 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
+    """
+    # inicialize the return variable
+    result: str | None = None
+
+    if logger:
+        logger.debug(msg=f"Issue a JWT token for '{account_id}'")
+    op_errors: list[str] = []
+
+    try:
+        result = __jwt_registry.issue_token(account_id=account_id,
+                                            nature=nature,
+                                            duration=duration,
+                                            claims=claims,
+                                            grace_interval=grace_interval,
+                                            logger=logger)
+        if logger:
+            logger.debug(msg=f"Token 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_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 or refresh, and return, the JWT token data associated with *account_id*.
+    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:
     {
@@ -328,26 +384,29 @@ def jwt_get_tokens(errors: list[str] | None,
     result: dict[str, Any] | None = None
 
     if logger:
-        logger.debug(msg=f"Retrieve JWT token data for '{account_id}'")
+        logger.debug(msg=f"Return JWT token data for '{account_id}'")
     op_errors: list[str] = []
+
+    # verify whether this refresh token is legitimate
     if refresh_token:
-        # verify whether this refresh token is legitimate
         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:
-            result = __jwt_data.issue_tokens(account_id=account_id,
-                                             account_claims=account_claims,
-                                             logger=logger)
+            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:

pypomes_jwt-0.9.0/src/pypomes_jwt/jwt_data.py → pypomes_jwt-0.9.2/src/pypomes_jwt/jwt_registry.py

@@ -18,9 +18,9 @@ from .jwt_constants import (
 )
 
 
-class JwtData:
+class JwtRegistry:
     """
-    Shared JWT data for security token access.
+    Shared JWT registry for security token access.
 
     Instance variables:
       - access_lock: lock for safe multi-threading access
@@ -59,12 +59,13 @@ class JwtData:
     as token-related and account-related. All times are UTC.
 
     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)
-      "nat": <string>           # nature of token (A: access; R: refresh) - locally issued tokens, only
+      # optional
       "aud": <string>           # token audience
       "nbt": <timestamp>        # not before time
 
@@ -72,20 +73,20 @@ class JwtData:
     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>         # value used to associate a client session with a token
+       "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
 
     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:
         """
@@ -110,7 +111,7 @@ class JwtData:
         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.
 
@@ -173,6 +174,73 @@ class JwtData:
 
         return account_data is not None
 
+    def issue_token(self,
+                    account_id: str,
+                    nature: str,
+                    duration: int,
+                    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 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).
+        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, 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: 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
+        :raises RuntimeError: invalid parameter
+        """
+        # validate some parameters
+        err_msg: str | None = None
+        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:
+            if logger:
+                logger.error(err_msg)
+            raise RuntimeError(err_msg)
+
+        # 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] = {}
+        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
+        if grace_interval:
+            current_claims["nbf"] = just_now + grace_interval
+            current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["nbf"],
+                                                                  tz=timezone.utc).isoformat()
+        else:
+            current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["iat"],
+                                                                  tz=timezone.utc).isoformat()
+        current_claims["exp"] = just_now + duration
+        current_claims["valid-until"] = datetime.fromtimestamp(timestamp=current_claims["exp"],
+                                                               tz=timezone.utc).isoformat()
+        # may raise an exception
+        return jwt.encode(payload=current_claims,
+                          key=JWT_ENCODING_KEY,
+                          algorithm=JWT_DEFAULT_ALGORITHM,
+                          headers={"kid": nature})
+
     def issue_tokens(self,
                      account_id: str,
                      account_claims: dict[str, Any] = None,
@@ -180,6 +248,9 @@ class JwtData:
         """
         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>,
@@ -191,125 +262,118 @@ class JwtData:
         :param account_id: the account identification
         :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
-        :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
-        :raises ImmatureSignatureError: 'nbf' or 'iat' claim represents a timestamp in the future
-        :raises InvalidAudienceError: 'aud' claim does not match one of the expected audience
-        :raises InvalidAlgorithmError: the specified algorithm is not recognized
-        :raises InvalidIssuerError: 'iss' claim does not match the expected issuer
-        :raises InvalidIssuedAtError: 'iat' claim is non-numeric
-        :raises MissingRequiredClaimError: a required claim is not contained in the claimset
-        :raises RuntimeError: error accessing the token database
+        :return: the JWT token data
+        :raises RuntimeError: invalid account id, or error accessing the token database
         """
         # 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.access_data.get(account_id)
-
-            # was the JWT data obtained ?
-            if account_data:
-                # yes, proceed
-                errors: list[str] = []
-                current_claims: dict[str, Any] = account_data.get("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")
-
-                # where is the JWT service provider ?
-                if account_data.get("remote-provider"):
-                    # JWT service is being provided by a remote server
-                    # Structure of the return data:
-                    # {
-                    #   "access_token": <jwt-token>,
-                    #   "created_in": <timestamp>,
-                    #   "expires_in": <seconds-to-expiration>,
-                    #   "refresh_token": <jwt-token>
-                    #   ...
-                    # }
-                    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))
+            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()
+            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"):
+                # JWT service is being provided by a remote server
+                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
+                just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
+                current_claims["iat"] = just_now
+                grace_interval = account_data.get("grace-interval")
+                if grace_interval:
+                    current_claims["nbf"] = just_now + grace_interval
+                    current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["nbf"],
+                                                                          tz=timezone.utc).isoformat()
                 else:
-                    # JWT service is being provided locally
-                    just_now: int = int(datetime.now(tz=timezone.utc).timestamp())
-                    current_claims["iat"] = just_now
-                    grace_interval = account_data.get("grace-interval")
-                    if grace_interval:
-                        account_data["nbf"] = just_now + grace_interval
-                        current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["nbf"],
-                                                                              tz=timezone.utc).isoformat()
-                    else:
-                        current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["iat"],
-                                                                              tz=timezone.utc).isoformat()
-                    # issue a candidate refresh token first, and persist it
-                    current_claims["exp"] = just_now + account_data.get("refresh-max-age")
-                    current_claims["valid-until"] = datetime.fromtimestamp(timestamp=current_claims["exp"],
-                                                                           tz=timezone.utc).isoformat()
-                    # may raise an exception
-                    refresh_token: str = jwt.encode(payload=current_claims,
-                                                    key=JWT_ENCODING_KEY,
-                                                    algorithm=JWT_DEFAULT_ALGORITHM,
-                                                    headers={"kid": "R0"})
-                    # obtain a DB connection (may raise an exception)
-                    db_conn: Any = db_connect(errors=errors,
-                                              logger=logger)
-                    # persist the candidate token (may raise an exception)
-                    token_id: int = _jwt_persist_token(errors=errors,
-                                                       account_id=account_id,
-                                                       jwt_token=refresh_token,
-                                                       db_conn=db_conn,
-                                                       logger=logger)
-                    # issue the definitive refresh token
-                    refresh_token = jwt.encode(payload=current_claims,
+                    current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["iat"],
+                                                                          tz=timezone.utc).isoformat()
+                # issue a candidate refresh token first, and persist it
+                current_claims["exp"] = just_now + account_data.get("refresh-max-age")
+                current_claims["valid-until"] = datetime.fromtimestamp(timestamp=current_claims["exp"],
+                                                                       tz=timezone.utc).isoformat()
+                # may raise an exception
+                refresh_token: str = jwt.encode(payload=current_claims,
+                                                key=JWT_ENCODING_KEY,
+                                                algorithm=JWT_DEFAULT_ALGORITHM,
+                                                headers={"kid": "R0"})
+                # obtain a DB connection (may raise an exception)
+                db_conn: Any = db_connect(errors=errors,
+                                          logger=logger)
+                # persist the candidate token (may raise an exception)
+                token_id: int = _jwt_persist_token(errors=errors,
+                                                   account_id=account_id,
+                                                   jwt_token=refresh_token,
+                                                   db_conn=db_conn,
+                                                   logger=logger)
+                # issue the definitive refresh token
+                refresh_token = jwt.encode(payload=current_claims,
+                                           key=JWT_ENCODING_KEY,
+                                           algorithm=JWT_DEFAULT_ALGORITHM,
+                                           headers={"kid": f"R{token_id}"})
+                # persist it
+                db_update(errors=errors,
+                          update_stmt=f"UPDATE {JWT_DB_TABLE}",
+                          update_data={JWT_DB_COL_TOKEN: refresh_token},
+                          where_data={JWT_DB_COL_KID: token_id},
+                          connection=db_conn,
+                          logger=logger)
+                # commit the transaction
+                db_commit(errors=errors,
+                          connection=db_conn,
+                          logger=logger)
+                if errors:
+                    raise RuntimeError("; ".join(errors))
+
+                # issue the access token
+                current_claims["exp"] = just_now + account_data.get("access-max-age")
+                # may raise an exception
+                access_token: str = jwt.encode(payload=current_claims,
                                                key=JWT_ENCODING_KEY,
                                                algorithm=JWT_DEFAULT_ALGORITHM,
-                                               headers={"kid": f"R{token_id}"})
-                    # persist it
-                    db_update(errors=errors,
-                              update_stmt=f"UPDATE {JWT_DB_TABLE}",
-                              update_data={JWT_DB_COL_TOKEN: refresh_token},
-                              where_data={JWT_DB_COL_KID: token_id},
-                              connection=db_conn,
-                              logger=logger)
-                    # commit the transaction
-                    db_commit(errors=errors,
-                              connection=db_conn,
-                              logger=logger)
-                    if errors:
-                        raise RuntimeError("; ".join(errors))
-
-                    # issue the access token
-                    current_claims["exp"] = just_now + account_data.get("access-max-age")
-                    # may raise an exception
-                    access_token: str = jwt.encode(payload=current_claims,
-                                                   key=JWT_ENCODING_KEY,
-                                                   algorithm=JWT_DEFAULT_ALGORITHM,
-                                                   headers={"kid": f"A{token_id}"})
-                    # return the token data
-                    result = {
-                        "access_token": access_token,
-                        "created_in": current_claims.get("iat"),
-                        "expires_in": current_claims.get("exp"),
-                        "refresh_token": refresh_token
-                    }
-            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)
+                                               headers={"kid": f"A{token_id}"})
+                # return the token data
+                result = {
+                    "access_token": access_token,
+                    "created_in": current_claims.get("iat"),
+                    "expires_in": current_claims.get("exp"),
+                    "refresh_token": refresh_token
+                }
+
+        return result
+
+    def __get_account_data(self,
+                           account_id: str,
+                           logger: Logger = None) -> dict[str, Any]:
+        """
+        Retrieve the JWT access data associated with *account_id*.
+
+        :return: the JWT access data associated with *account_id*
+        :raises RuntimeError: No JWT access data exists for *account_id*
+        """
+        # retrieve the access data
+        result: dict[str, Any] = self.access_data.get(account_id)
+        if not 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
 
@@ -389,7 +453,7 @@ def _jwt_persist_token(errors: list[str],
     :param db_conn: the database connection to use
     :param logger: optional logger
     :return: the storage id of the inserted token
-    :raises RuntimeError: error accessing the revocation database
+    :raises RuntimeError: error accessing the token database
     """
     from pypomes_db import db_select, db_insert, db_delete
     from .jwt_pomes import jwt_get_claims