jamlib 3.1.0__tar.gz → 3.2.0b1__tar.gz

{jamlib-3.1.0/src/jamlib.egg-info → jamlib-3.2.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jamlib
-Version: 3.1.0
+Version: 3.2.0b1
 Summary: Simple and universal library for authorization.
 Author-email: Makridenko Adrian <adrianmakridenko@duck.com>, Ksenia Travnikova <kseniatravnikova@duck.com>
 License: Apache-2.0

{jamlib-3.1.0 → jamlib-3.2.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jamlib"
-version = "3.1.0"
+version = "3.2.0b1"
 description = "Simple and universal library for authorization."
 authors = [
     {name = "Makridenko Adrian",email = "adrianmakridenko@duck.com"},

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/__base__.py

@@ -6,7 +6,7 @@ from typing import Any, Literal
 
 from jam.encoders import BaseEncoder, JsonEncoder
 from jam.exceptions import JamConfigurationError
-from jam.jwt.__base__ import BaseJWT
+from jam.jose.__base__ import BaseJWT
 from jam.logger import BaseLogger, JamLogger
 from jam.oauth2.__base__ import BaseOAuth2Client
 from jam.otp.__base__ import BaseOTP, OTPConfig
@@ -189,36 +189,41 @@ class BaseJam(ABC):
                 raise JamConfigurationError(message="Unknown OTP type.")
 
     @abstractmethod
-    def jwt_make_payload(
-        self, exp: int | None, data: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Make JWT-specific payload.
-
-        Args:
-            exp (int | None): Token expire, if None -> use default
-            data (dict[str, Any]): Data to payload
-
-        Returns:
-            dict[str, Any]: Payload
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    def jwt_create(self, payload: dict[str, Any]) -> str:
-        """Create JWT token.
+    def jwt_encode(
+        self,
+        iss: str | None = None,
+        sub: str | None = None,
+        aud: str | None = None,
+        exp: int | None = None,
+        nbf: int | None = None,
+        *,
+        payload: dict[str, Any] | None = None,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encode the JWT with the given expire, header, and payload.
 
         Args:
-            payload (dict[str, Any]): Data payload
+            exp (int | None): The expiration time in seconds.
+            nbf (int | None): The not-before time in seconds.
+            iss (str | None): The issuer.
+            sub (str | None): The subject.
+            aud (str | None): The audience.
+            header (dict[str, Any] | None): The header to include in the JWT.
+            payload (dict[str, Any] | None): The payload to include in the JWT.
 
         Returns:
-            str: New token
-
+            str: The encoded JWT.
         """
         raise NotImplementedError
 
     @abstractmethod
     def jwt_decode(
-        self, token: str, check_exp: bool = True, check_list: bool = True
+        self,
+        token: str,
+        check_exp: bool = True,
+        check_list: bool = True,
+        check_nbf: bool = False,
+        include_headers: bool = False,
     ) -> dict[str, Any]:
         """Verify and decode JWT token.
 
@@ -226,6 +231,8 @@ class BaseJam(ABC):
             token (str): JWT token
             check_exp (bool): Check expire
             check_list (bool): Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/
+            check_nbf (bool): Check not-before time
+            include_headers (bool): Include headers in the decoded payload
 
         Returns:
             dict[str, Any]: Decoded payload

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/__deprecated__.py

@@ -8,7 +8,7 @@ def deprecated(replacement: str | None = None):
     """Mark funcs are deprecated."""
 
     def decorator(func):
-        msg = f"Function {func.__name__}() is deprecated."
+        msg = f"{func.__name__}() is deprecated."
         if replacement:
             msg += f" {replacement}"
 

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/__init__.py

@@ -12,5 +12,5 @@ from jam.encoders import JsonEncoder
 from jam.instance import Jam
 
 
-__version__ = "3.0.0"
+__version__ = "3.2.0b1"
 __all__ = ["Jam", "JsonEncoder", "BaseJam", "BaseEncoder"]

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/aio/__base__.py

@@ -45,9 +45,42 @@ class BaseAsyncJam(BaseJam):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def jwt_encode(
+        self,
+        iss: str | None = None,
+        sub: str | None = None,
+        aud: str | None = None,
+        exp: int | None = None,
+        nbf: int | None = None,
+        *,
+        payload: dict[str, Any] | None = None,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encode the JWT with the given expire, header, and payload.
+
+        Args:
+            exp (int | None): The expiration time in seconds.
+            nbf (int | None): The not-before time in seconds.
+            iss (str | None): The issuer.
+            sub (str | None): The subject.
+            aud (str | None): The audience.
+            header (dict[str, Any] | None): The header to include in the JWT.
+            payload (dict[str, Any] | None): The payload to include in the JWT.
+
+        Returns:
+            str: The encoded JWT.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     async def jwt_decode(  # type: ignore[override]
-        self, token: str, check_exp: bool = True, check_list: bool = True
+        self,
+        token: str,
+        check_exp: bool = True,
+        check_list: bool = True,
+        check_nbf: bool = False,
+        include_headers: bool = False,
     ) -> dict[str, Any]:
         """Verify and decode JWT token.
 
@@ -55,6 +88,8 @@ class BaseAsyncJam(BaseJam):
             token (str): JWT token
             check_exp (bool): Check expire
             check_list (bool): Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/
+            check_nbf (bool): Check not-before time
+            include_headers (bool): Include headers in the decoded payload
 
         Returns:
             dict[str, Any]: Decoded payload

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/aio/instance.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 import datetime
+import time
 from typing import Any
 import uuid
 
@@ -10,6 +11,7 @@ from jam.exceptions import (
     JamJWTExpired,
     JamJWTInBlackList,
     JamJWTNotInWhiteList,
+    JamJWTNotYetValid,
 )
 
 
@@ -68,8 +70,52 @@ class Jam(BaseAsyncJam):
 
         return token
 
+    async def jwt_encode(
+        self,
+        iss: str | None = None,
+        sub: str | None = None,
+        aud: str | None = None,
+        exp: int | None = None,
+        nbf: int | None = None,
+        *,
+        payload: dict[str, Any] | None = None,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encode the JWT with the given expire, header, and payload.
+
+        Args:
+            exp (int | None): The expiration time in seconds.
+            nbf (int | None): The not-before time in seconds.
+            iss (str | None): The issuer.
+            sub (str | None): The subject.
+            aud (str | None): The audience.
+            header (dict[str, Any] | None): The header to include in the JWT.
+            payload (dict[str, Any] | None): The payload to include in the JWT.
+
+        Returns:
+            str: The encoded JWT.
+        """
+        assert self.jwt is not None
+        token = self.jwt.encode(
+            iss=iss,
+            sub=sub,
+            aud=aud,
+            exp=exp,
+            nbf=nbf,
+            payload=payload,
+            header=header,
+        )
+        if self.jwt.list and self.jwt.list.__list_type__ == "white":
+            self.jwt.list.add(token)
+        return token
+
     async def jwt_decode(
-        self, token: str, check_exp: bool = True, check_list: bool = True
+        self,
+        token: str,
+        check_exp: bool = True,
+        check_list: bool = True,
+        check_nbf: bool = False,
+        include_headers: bool = False,
     ) -> dict[str, Any]:
         """Verify and decode JWT token.
 
@@ -77,23 +123,43 @@ class Jam(BaseAsyncJam):
             token (str): JWT token
             check_exp (bool): Check expire
             check_list (bool): Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/
+            check_nbf (bool): Check not-before time
+            include_headers (bool): Include headers in the decoded payload
 
         Returns:
             dict[str, Any]: Decoded payload
+
+        Raises:
+            JamJWTExpired: If token is expired
+            JamJWTNotYetValid: If token is not yet valid (nbf claim)
+            JamConfigurationError: If JWT list is not connected
+            JamJWTNotInWhiteList: If token is not in white list
+            JamJWTInBlackList: If token is in black list
         """
         assert self.jwt is not None
         self._logger.debug(
-            f"Verifying JWT token (length: {len(token)} chars), check_exp={check_exp}, check_list={check_list}"
+            f"Verifying JWT token (length: {len(token)} chars), check_exp={check_exp}, check_list={check_list}, check_nbf={check_nbf}"
         )
-        payload = self.jwt.decode(token)
+        data = self.jwt.decode(token)
+        if "payload" in data:
+            payload = data["payload"]
+            headers = data.get("header")
+        else:
+            payload = data
+            headers = None
+
+        if check_exp and "exp" in payload:
+            if payload["exp"] < time.time():
+                raise JamJWTExpired
+
+        if check_nbf and "nbf" in payload:
+            if payload["nbf"] > time.time():
+                raise JamJWTNotYetValid
+
         self._logger.debug(
             f"JWT token verified successfully, payload keys: {list(payload.keys())}"
         )
 
-        if check_exp:
-            if payload["exp"] < datetime.datetime.now().timestamp():
-                raise JamJWTExpired
-
         if check_list:
             if not self.jwt.list:
                 raise JamConfigurationError(
@@ -113,6 +179,9 @@ class Jam(BaseAsyncJam):
                             message="Invalid JWT list type",
                             error_code="configuration.jwt.unknown_list_type",
                         )
+
+        if include_headers and headers is not None:
+            return {"header": headers, "payload": payload}
         return payload
 
     async def session_create(

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/exceptions/__init__.py

@@ -1,49 +1,49 @@
 # -*- coding: utf-8 -*-
 
-"""
-All Jam exceptions
-"""
+"""All Jam exceptions"""
 
-from .base import JamError, JamConfigurationError, JamValidationError
-
-from .oauth2 import (
-    JamOAuth2Error,
-    JamOAuth2EmptyRaw,
-    JamOAuth2ProviderNotConfigured,
+from .base import JamConfigurationError, JamError, JamValidationError
+from .jose import (
+    JamJWEEncryptionError,
+    JamJWEDecryptionError,
+    JamJWKValidationError,
+    JamJWSVerificationError,
 )
-
 from .jwt import (
+    JamJWTEmptyPrivateKey,
+    JamJWTEmptySecretKey,
     JamJWTExpired,
     JamJWTInBlackList,
     JamJWTNotInWhiteList,
-    JamJWTEmptyPrivateKey,
-    JamJWTEmptySecretKey,
+    JamJWTNotYetValid,
     JamJWTUnsupportedAlgorithm,
     JamJWTValidationError,
 )
-
+from .oauth2 import (
+    JamOAuth2EmptyRaw,
+    JamOAuth2Error,
+    JamOAuth2ProviderNotConfigured,
+)
 from .paseto import (
-    JamPASETOInvalidSymmetricKey,
-    JamPASETOInvalidRSAKey,
     JamPASETOInvalidED25519Key,
-    JamPASETOInvalidSecp384r1Key,
-    JamPASTOKeyVerificationError,
     JamPASETOInvalidPurpose,
+    JamPASETOInvalidRSAKey,
+    JamPASETOInvalidSecp384r1Key,
+    JamPASETOInvalidSymmetricKey,
     JamPASETOInvalidTokenFormat,
+    JamPASTOKeyVerificationError,
 )
-
 from .plugins import (
     JamFlaskPluginConfigError,
     JamFlaskPluginError,
     JamLitestarPluginConfigError,
     JamLitestarPluginError,
     JamStarlettePluginConfigError,
-    JamStarlettePluginError
+    JamStarlettePluginError,
 )
-
 from .sessions import (
-    JamSessionNotFound,
     JamSessionEmptyAESKey,
+    JamSessionNotFound,
 )
 
 
@@ -57,10 +57,15 @@ __all__ = [
     "JamJWTExpired",
     "JamJWTInBlackList",
     "JamJWTNotInWhiteList",
+    "JamJWTNotYetValid",
     "JamJWTEmptyPrivateKey",
     "JamJWTEmptySecretKey",
     "JamJWTUnsupportedAlgorithm",
     "JamJWTValidationError",
+    "JamJWSVerificationError",
+    "JamJWKValidationError",
+    "JamJWEEncryptionError",
+    "JamJWEDecryptionError",
     "JamPASETOInvalidSymmetricKey",
     "JamPASETOInvalidRSAKey",
     "JamPASETOInvalidED25519Key",

jamlib-3.2.0b1/src/jam/exceptions/jose.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+from .base import JamValidationError
+
+
+class JamJWSVerificationError(JamValidationError):
+    default_message = "JWS signature verification failed."
+    default_code = "jws.verification_error"
+
+
+class JamJWKValidationError(JamValidationError):
+    default_message = "JWK validation failed."
+    default_code = "jwk.validation_error"
+
+
+class JamJWEEncryptionError(JamValidationError):
+    default_message = "JWE encryption failed."
+    default_code = "jwe.encryption_error"
+
+
+class JamJWEDecryptionError(JamValidationError):
+    default_message = "JWE decryption failed."
+    default_code = "jwe.decryption_error"

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/exceptions/jwt.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-from .base import JamError, JamValidationError, JamConfigurationError
+from .base import JamConfigurationError, JamError, JamValidationError
 
 
 class JamJWTExpired(JamError):
@@ -8,6 +8,11 @@ class JamJWTExpired(JamError):
     default_code = "jwt.token_expired"
 
 
+class JamJWTNotYetValid(JamError):
+    default_message = "Token is not yet valid (nbf claim)."
+    default_code = "jwt.token_not_yet_valid"
+
+
 class JamJWTInBlackList(JamError):
     default_message = "Token in blacklist."
     default_code = "jwt.blacklist"
@@ -24,7 +29,9 @@ class JamJWTEmptySecretKey(JamConfigurationError):
 
 
 class JamJWTEmptyPrivateKey(JamConfigurationError):
-    default_message = "For asymmetric encryption, you must specify `private_key`."
+    default_message = (
+        "For asymmetric encryption, you must specify `private_key`."
+    )
     default_code = "jwt.config.empty_private_key"
 
 

{jamlib-3.1.0 → jamlib-3.2.0b1}/src/jam/instance.py

@@ -1,15 +1,18 @@
 # -*- coding: utf-8 -*-
 
 import datetime
+import time
 from typing import Any
 import uuid
 
 from jam.__base__ import BaseJam
+from jam.__deprecated__ import deprecated
 from jam.exceptions import (
     JamConfigurationError,
     JamJWTExpired,
     JamJWTInBlackList,
     JamJWTNotInWhiteList,
+    JamJWTNotYetValid,
 )
 
 
@@ -17,18 +20,24 @@ class Jam(BaseJam):
     """Main instance."""
 
     MODULES: dict[str, str] = {
-        "jwt": "jam.jwt.create_instance",
+        "jwt": "jam.jose.JWT",
         "session": "jam.sessions.create_instance",
         "oauth2": "jam.oauth2.create_instance",
         "paseto": "jam.paseto.create_instance",
         "otp": "jam.otp.__base__.OTPConfig",
     }
 
+    @deprecated(
+        "This method is deprecated; the JWT payload is generated automatically in accordance with the specification."
+    )
     def jwt_make_payload(
         self, exp: int | None, data: dict[str, Any]
     ) -> dict[str, Any]:
         """Make JWT-specific payload.
 
+        !!! Deprecated
+                This method is deprecated; the JWT payload is generated automatically in accordance with the specification.
+
         Args:
             exp (int | None): Token expire
             data (dict[str, Any]): Data to payload
@@ -44,9 +53,13 @@ class Jam(BaseJam):
         payload = payload | data
         return payload
 
+    @deprecated("Use jam.jwt_encode")
     def jwt_create(self, payload: dict[str, Any]) -> str:
         """Create JWT token.
 
+        !!! Deprecated
+                Use Jam.jwt_encode
+
         Args:
             payload (dict[str, Any]): Data payload
 
@@ -68,8 +81,52 @@ class Jam(BaseJam):
 
         return token
 
+    def jwt_encode(
+        self,
+        iss: str | None = None,
+        sub: str | None = None,
+        aud: str | None = None,
+        exp: int | None = None,
+        nbf: int | None = None,
+        *,
+        payload: dict[str, Any] | None = None,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encode the JWT with the given expire, header, and payload.
+
+        Args:
+            exp (int | None): The expiration time in seconds.
+            nbf (int | None): The not-before time in seconds.
+            iss (str | None): The issuer.
+            sub (str | None): The subject.
+            aud (str | None): The audience.
+            header (dict[str, Any] | None): The header to include in the JWT.
+            payload (dict[str, Any] | None): The payload to include in the JWT.
+
+        Returns:
+            str: The encoded JWT.
+        """
+        assert self.jwt is not None
+        token = self.jwt.encode(
+            iss=iss,
+            sub=sub,
+            aud=aud,
+            exp=exp,
+            nbf=nbf,
+            payload=payload,
+            header=header,
+        )
+        if self.jwt.list and self.jwt.list.__list_type__ == "white":
+            self.jwt.list.add(token)
+        return token
+
     def jwt_decode(
-        self, token: str, check_exp: bool = True, check_list: bool = True
+        self,
+        token: str,
+        check_exp: bool = True,
+        check_list: bool = True,
+        check_nbf: bool = False,
+        include_headers: bool = False,
     ) -> dict[str, Any]:
         """Verify and decode JWT token.
 
@@ -77,29 +134,38 @@ class Jam(BaseJam):
             token (str): JWT token
             check_exp (bool): Check expire
             check_list (bool): Check white/black list. Docs: https://jam.makridenko.ru/jwt/lists/what/
+            check_nbf (bool): Check not-before time
+            include_headers (bool): Include headers in the decoded payload
 
         Returns:
             dict[str, Any]: Decoded payload
 
         Raises:
             JamJWTExpired: If token is expired
+            JamJWTNotYetValid: If token is not yet valid (nbf claim)
             JamConfigurationError: If JWT list is not connected
             JamJWTNotInWhiteList: If token is not in white list
             JamJWTInBlackList: If token is in black list
         """
         self._logger.debug(
-            f"Verifying JWT token (length: {len(token)} chars), check_exp={check_exp}, check_list={check_list}"
+            f"Verifying JWT token (length: {len(token)} chars), check_exp={check_exp}, check_list={check_list}, check_nbf={check_nbf}"
         )
         assert self.jwt is not None
-        payload = self.jwt.decode(token)
+        data = self.jwt.decode(token)
+        payload = data["payload"]
+
+        if check_exp and "exp" in payload:
+            if payload["exp"] < time.time():
+                raise JamJWTExpired
+
+        if check_nbf and "nbf" in payload:
+            if payload["nbf"] > time.time():
+                raise JamJWTNotYetValid
+
         self._logger.debug(
             f"JWT token verified successfully, payload keys: {list(payload.keys())}"
         )
 
-        if check_exp:
-            if payload["exp"] < datetime.datetime.now().timestamp():
-                raise JamJWTExpired
-
         if check_list:
             if not self.jwt.list:
                 raise JamConfigurationError(
@@ -119,6 +185,9 @@ class Jam(BaseJam):
                             message="Invalid JWT list type",
                             error_code="configuration.jwt.unknown_list_type",
                         )
+
+        if include_headers:
+            return data
         return payload
 
     def session_create(self, session_key: str, data: dict[str, Any]) -> str:
@@ -391,9 +460,9 @@ class Jam(BaseJam):
         Returns:
             dict: Payload
         """
-        from jam.paseto.utils import payload_maker
+        from jam.paseto.utils import payload_maker as pm
 
-        return payload_maker(expire=exp, data=data)
+        return pm(expire=exp, data=data)
 
     def paseto_create(
         self,