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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_jwt
-Version: 0.8.9
+Version: 0.9.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
@@ -13,4 +13,4 @@ Requires-Python: >=3.12
 Requires-Dist: cryptography>=44.0.2
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pypomes-core>=1.8.5
-Requires-Dist: pypomes-db>=1.9.6
+Requires-Dist: pypomes-db>=1.9.7

{pypomes_jwt-0.8.9 → pypomes_jwt-0.9.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_jwt"
-version = "0.8.9"
+version = "0.9.1"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -22,7 +22,7 @@ dependencies = [
     "PyJWT>=2.10.1",
     "cryptography>=44.0.2",
     "pypomes_core>=1.8.5",
-    "pypomes_db>=1.9.6"
+    "pypomes_db>=1.9.7"
 ]
 
 [project.urls]

{pypomes_jwt-0.8.9 → pypomes_jwt-0.9.1}/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.8.9 → pypomes_jwt-0.9.1}/src/pypomes_jwt/jwt_pomes.py

@@ -1,9 +1,9 @@
-import base64
 import jwt
+from base64 import urlsafe_b64decode
 from flask import Request, Response, request
 from logging import Logger
 from pypomes_db import db_select, db_delete
-from typing import Any, Literal
+from typing import Any
 
 from . import JWT_DB_COL_ACCOUNT
 from .jwt_constants import (
@@ -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",
+                           nature=["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,23 +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: Literal["A", "R"] = None,
+                       nature: 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.
 
     :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 nature: one of 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
@@ -179,17 +182,17 @@ def jwt_validate_token(errors: list[str] | None,
 
     # extract needed data from token header
     token_header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
-    token_kid: int = int(token_header.get("kid") or 0)
+    token_kid: str = token_header.get("kid")
     token_alg: str | None = None
     token_decoder: bytes | None = None
     op_errors: list[str] = []
 
     # retrieve token data from database
-    if (nature == "R" and not token_kid) or (nature == "A" and token_kid):
-        nat: str = "an access" if nature == "A" else "a refresh"
-        op_errors.append(f"Token is not {nat} token")
-    elif token_kid:
-        where_data: dict[str, str] = {JWT_DB_COL_KID: token_kid}
+    if nature and not (token_kid and token_kid[0:1] in nature):
+        op_errors.append("Invalid token")
+    elif token_kid and len(token_kid) > 1 and token_kid[0:1].isupper() and token[1:].isdigit():
+        # token was likely issued locally
+        where_data: dict[str, Any] = {JWT_DB_COL_KID: int(token_kid[1:])}
         if account_id:
             where_data[JWT_DB_COL_ACCOUNT] = account_id
         recs: list[tuple[str]] = db_select(errors=op_errors,
@@ -199,7 +202,7 @@ def jwt_validate_token(errors: list[str] | None,
                                            logger=logger)
         if recs:
             token_alg = recs[0][0]
-            token_decoder = base64.urlsafe_b64decode(recs[0][1])
+            token_decoder = urlsafe_b64decode(recs[0][1])
         else:
             op_errors.append("Invalid token")
     else:
@@ -215,9 +218,7 @@ def jwt_validate_token(errors: list[str] | None,
             #   ExpiredSignatureError: token and refresh period have expired
             #   InvalidSignatureError: signature does not match the one provided as part of the token
             #   ImmatureSignatureError: 'nbf' or 'iat' claim represents a timestamp in the future
-            #   InvalidAudienceError: 'aud' claim does not match one of the expected audience
             #   InvalidAlgorithmError: the specified algorithm is not recognized
-            #   InvalidIssuerError: 'iss' claim does not match the expected issuer
             #   InvalidIssuedAtError: 'iat' claim is non-numeric
             #   MissingRequiredClaimError: a required claim is not contained in the claimset
             payload: dict[str, Any] = jwt.decode(jwt=token,
@@ -227,7 +228,7 @@ def jwt_validate_token(errors: list[str] | None,
                                                      "verify_nbf": True
                                                  },
                                                  key=token_decoder,
-                                                 require=["exp"],
+                                                 require=["iat", "iss", "exp", "sub"],
                                                  algorithms=token_alg)
             if account_id and payload.get("sub") != account_id:
                 op_errors.append("Token does not belong to account")
@@ -275,15 +276,15 @@ 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="R",
+                                                      nature=["A", "R"],
                                                       account_id=account_id,
                                                       logger=logger)
     if not op_errors:
-        token_kid: int = int(token_claims["header"].get("kid") or 0)
+        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: token_kid,
+                      JWT_DB_COL_KID: int(token_kid[1:]),
                       JWT_DB_COL_ACCOUNT: account_id
                   },
                   logger=logger)
@@ -298,13 +299,66 @@ 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,
+                    claims: dict[str, Any],
+                    grace_interval: int = None,
+                    logger: Logger = None) -> str:
+    """
+    Issue or refresh, and return, a JWT token associated with *account_id*, of the specified *nature*.
+
+    The parameter *nature* must be a single uppercase, unaccented letter, different from "A"
+    (used to indicate *access* tokens) and *R* (used to indicate *refresh* tokens).
+    The parameter *duration* specifies the token's validity interval (at least 60 seconds).
+    The token's *claims* should contain the claim *iss*.
+
+    :param errors: incidental error messages
+    :param account_id: the account identification
+    :param nature: the token's nature (a single uppercase, unaccented letter different from "A" and "R")
+    :param duration: the number of seconds for the token to remain valid (at least 60 seconds)
+    :param claims: the token's claims (must contain at least the claim "iss")
+    :param 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
     """
-    Issue or refresh, and return, the JWT token data associated with *account_id*.
+    # 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 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.
@@ -328,13 +382,14 @@ 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",
+                                             nature=["R"],
                                              account_id=account_id,
                                              logger=logger) or {}).get("payload")
         if account_claims:
@@ -343,11 +398,12 @@ def jwt_get_tokens(errors: list[str] | None,
             account_claims.pop("iss", None)
             account_claims.pop("exp", None)
             account_claims.pop("nbt", 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:
@@ -380,7 +436,7 @@ def jwt_get_claims(errors: list[str] | None,
         "header": {
           "alg": "RS256",
           "typ": "JWT",
-          "kid": "1234"
+          "kid": "A1234"
         },
         "payload": {
           "valid-from": <YYYY-MM-DDThh:mm:ss+00:00>

pypomes_jwt-0.8.9/src/pypomes_jwt/jwt_data.py → pypomes_jwt-0.9.1/src/pypomes_jwt/jwt_registry.py

@@ -1,8 +1,8 @@
-import base64
 import jwt
 import requests
 import string
 import sys
+from base64 import urlsafe_b64encode
 from datetime import datetime, timezone
 from logging import Logger
 from pypomes_core import str_random
@@ -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
@@ -33,11 +33,13 @@ class JwtData:
            "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
+           # optional
            "token-audience": <string>    # the audience the token is intended for
            "token_nonce": <string>       # value used to associate a client session with a token
            "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
              "birthdate": <string>,      # subject's birth date
              "email": <string>,          # subject's email
              "gender": <string>,         # subject's gender
@@ -57,13 +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:
+      # optional
       "aud": <string>           # token audience
       "nbt": <timestamp>        # not before time
 
@@ -71,18 +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'
-      "kid": <string>           # a reference to the encoding/decoding keys used
-                                # (if issued by the local server, holds the public key, if assimetric keys were used)
+      "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.
     """
     def __init__(self) -> None:
         """
@@ -170,6 +174,70 @@ class JwtData:
 
         return account_data is not None
 
+    def issue_token(self,
+                    account_id: str,
+                    nature: str,
+                    duration: int,
+                    claims: dict[str, Any],
+                    grace_interval: int = None,
+                    logger: Logger = None) -> str:
+        """
+        Issue an return a JWT token associated with *account_id*.
+
+        The parameter *nature* must be a single uppercase, unaccented letter, different from "A"
+        (used to indicate *access* tokens) and *R* (used to indicate *refresh* tokens).
+        The parameter *duration* specifies the token's validity interval (at least 60 seconds).
+        The token's *claims* should contain the claim *iss*.
+
+        :param account_id: the account identification
+        :param nature: the token's nature (a single uppercase, unaccented letter different from "A" and "R")
+        :param duration: the number of seconds for the token to remain valid (at least 60 seconds)
+        :param claims: the token's claims (must contain at least the claim "iss")
+        :param 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)
+
+        # make sure account data exists
+        self.__get_account_data(account_id=account_id,
+                                logger=logger)
+        # issue the token
+        current_claims: dict[str, Any] = claims.copy()
+        current_claims["jti"] = str_random(size=32,
+                                           chars=string.ascii_letters + string.digits)
+        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,
@@ -188,118 +256,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
         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
-
-                    # issue a candidate refresh token first, and persist it
-                    current_claims["exp"] = just_now + account_data.get("refresh-max-age")
                     current_claims["valid-from"] = datetime.fromtimestamp(timestamp=current_claims["iat"],
                                                                           tz=timezone.utc).isoformat()
-                    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)
-                    # 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,
+                # 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": str(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)
-                    # 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
 
@@ -379,7 +447,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
@@ -453,7 +521,7 @@ def _jwt_persist_token(errors: list[str],
               insert_data={JWT_DB_COL_ACCOUNT: account_id,
                            JWT_DB_COL_TOKEN: jwt_token,
                            JWT_DB_COL_ALGORITHM: JWT_DEFAULT_ALGORITHM,
-                           JWT_DB_COL_DECODER: base64.urlsafe_b64encode(JWT_DECODING_KEY).decode()},
+                           JWT_DB_COL_DECODER: urlsafe_b64encode(JWT_DECODING_KEY).decode()},
               connection=db_conn,
               logger=logger)
     if errors: