jamlib 3.2.0b2__tar.gz → 3.2.0rc0__tar.gz

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jamlib
-Version: 3.2.0b2
+Version: 3.2.0rc0
 Summary: Simple and universal library for authorization.
 Author-email: Makridenko Adrian <adrianmakridenko@duck.com>, Ksenia Travnikova <kseniatravnikova@duck.com>
 License: Apache-2.0
@@ -30,7 +30,7 @@ Classifier: Framework :: FastAPI
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: cryptography>=46.0.5
+Requires-Dist: cryptography>=48.0.0
 Provides-Extra: cli
 Requires-Dist: click>=8.3.1; extra == "cli"
 Provides-Extra: redis
@@ -85,7 +85,7 @@ otp_code = jam.otp_code(secret="3DB7FOAOFBCI3WFDRE7EPF43CA")
 ## Why Jam?
 Jam is a library that provides the most popular AUTH* mechanisms right out of the box.
 
-* [JWT](https://jam.makridenko.ru/usage/jwt/)
+* [JOSE](https://jam.makridenko.ru/usage/jose/index/)
 * [PASETO](https://jam.makridenko.ru/usage/paseto/)
 * [Server side sessions](https://jam.makridenko.ru/usage/sessions/)
 * [OTP](https://jam.makridenko.ru/usage/otp/)
@@ -109,7 +109,7 @@ Here is a comparison with other libraries:
 
 | Features / Library    | **Jam** | [Authx](https://authx.yezz.me/) | [PyJWT](https://pyjwt.readthedocs.io) | [AuthLib](https://docs.authlib.org) | [OTP Auth](https://otp.authlib.org/) |
 |-----------------------|--------|----------------------------------|---------------------------------------|-------------------------------------|--------------------------------------|
-| JWT                   | ✅     | ✅                               | ✅                                    | ✅                                  | ❌                                   |
+| JOSE                  | ✅     | ❌ only JWT                      | ❌ only JWT                           | ✅                                  | ❌                                   |
 | JWT black/white lists | ✅     | ❌                               | ❌                                    | ❌                                  | ❌                                   |
 | PASETO                | ✅     | ❌                               | ❌                                    | ❌                                  | ❌                                   |
 | Server side sessions  | ✅     | ✅                               | ❌                                    | ❌                                  | ❌                                   |

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/README.md

@@ -32,7 +32,7 @@ otp_code = jam.otp_code(secret="3DB7FOAOFBCI3WFDRE7EPF43CA")
 ## Why Jam?
 Jam is a library that provides the most popular AUTH* mechanisms right out of the box.
 
-* [JWT](https://jam.makridenko.ru/usage/jwt/)
+* [JOSE](https://jam.makridenko.ru/usage/jose/index/)
 * [PASETO](https://jam.makridenko.ru/usage/paseto/)
 * [Server side sessions](https://jam.makridenko.ru/usage/sessions/)
 * [OTP](https://jam.makridenko.ru/usage/otp/)
@@ -56,7 +56,7 @@ Here is a comparison with other libraries:
 
 | Features / Library    | **Jam** | [Authx](https://authx.yezz.me/) | [PyJWT](https://pyjwt.readthedocs.io) | [AuthLib](https://docs.authlib.org) | [OTP Auth](https://otp.authlib.org/) |
 |-----------------------|--------|----------------------------------|---------------------------------------|-------------------------------------|--------------------------------------|
-| JWT                   | ✅     | ✅                               | ✅                                    | ✅                                  | ❌                                   |
+| JOSE                  | ✅     | ❌ only JWT                      | ❌ only JWT                           | ✅                                  | ❌                                   |
 | JWT black/white lists | ✅     | ❌                               | ❌                                    | ❌                                  | ❌                                   |
 | PASETO                | ✅     | ❌                               | ❌                                    | ❌                                  | ❌                                   |
 | Server side sessions  | ✅     | ✅                               | ❌                                    | ❌                                  | ❌                                   |

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jamlib"
-version = "3.2.0b2"
+version = "3.2.0rc0"
 description = "Simple and universal library for authorization."
 authors = [
     {name = "Makridenko Adrian",email = "adrianmakridenko@duck.com"},
@@ -23,7 +23,7 @@ keywords = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "cryptography>=46.0.5",
+    "cryptography>=48.0.0",
 ]
 
 classifiers = [

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/src/jam/__base__.py

@@ -1,16 +1,21 @@
 # -*- coding: utf-8 -*-
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 import gc
+import os
 from typing import Any, Literal
 
-from jam.encoders import BaseEncoder, JsonEncoder
+from jam.__base_encoder__ import BaseEncoder
+from jam.encoders import JsonEncoder
 from jam.exceptions import JamConfigurationError
-from jam.jose.__base__ import BaseJWT
+from jam.jose.__base__ import BaseJWE, BaseJWS, BaseJWT
 from jam.logger import BaseLogger, JamLogger
 from jam.oauth2.__base__ import BaseOAuth2Client
 from jam.otp.__base__ import BaseOTP, OTPConfig
 from jam.paseto.__base__ import BasePASETO
+from jam.plugins.__base__ import BasePlugin
 from jam.sessions.__base__ import BaseSessionModule
 from jam.utils.config_maker import __config_maker__, __module_loader__
 
@@ -18,7 +23,7 @@ from jam.utils.config_maker import __config_maker__, __module_loader__
 class BaseJam(ABC):
     """Base jam instance."""
 
-    MODULES: dict[str, str] = {}
+    MODULES: dict[str, str | dict[str, str]] = {}
 
     def __init__(
         self,
@@ -30,15 +35,17 @@ class BaseJam(ABC):
             "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
         ] = "INFO",
         serializer: BaseEncoder | type[BaseEncoder] = JsonEncoder,
+        plugins: list[type[BasePlugin]] = [],
     ) -> None:
         """Initialize instance.
 
         Args:
-                config (Union[str, dict[str, Any]]): Configuration
-                pointer (str): Pointer
-                logger (BaseLogger): Logger
-                log_level (Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]): Log level
-                serializer (Union[BaseEncoder, type[BaseBrowser]]): Serializer
+            config (Union[str, dict[str, Any]]): Configuration
+            pointer (str): Pointer
+            logger (BaseLogger): Logger
+            log_level (Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]): Log level
+            serializer (Union[BaseEncoder, type[BaseBrowser]]): Serializer
+            plugins (list[type[BasePlugin]]): List of plugins
 
         Returns:
                 None
@@ -54,7 +61,12 @@ class BaseJam(ABC):
 
         self._logger = logger(log_level)
         self._serializer = serializer
+        self._plugins = []
+
         self.jwt: BaseJWT | None = None
+        self.jws: BaseJWS | None = None
+        self.jwe: BaseJWE | None = None
+        self.jose: dict[str, Any] | None = None
         self.session: BaseSessionModule | None = None
         self.oauth2: dict[str, BaseOAuth2Client] | None = None
         self.otp: OTPConfig | None = None
@@ -69,8 +81,11 @@ class BaseJam(ABC):
         )
         self._logger.debug(
             "BaseJam initialization complete. Modules loaded:\n"
-            f" jwt={self.jwt is not None}, session={self.session is not None}, oauth2={self.oauth2 is not None}"
+            f" jwt={self.jwt is not None}, jose={self.jose is not None}, session={self.session is not None}, oauth2={self.oauth2 is not None}"
         )
+        if os.getenv("JAM_ENABLE_PLUGINS", "0") == "1":
+            self._logger.warning("Experimental plugins are enabled!")
+            self.__setup_plugins(plugins)
         gc.collect()
 
     def __build_main_config(
@@ -139,6 +154,7 @@ class BaseJam(ABC):
         """Build instance.
 
         Load modules from configuration and initialize them.
+        Supports both flat modules (name -> path) and nested modules (name -> {subname -> path}).
 
         Args:
             config (dict[str, Any]): Configuration
@@ -151,24 +167,68 @@ class BaseJam(ABC):
                 self._logger.debug(f"Missing configuration for module {name}")
                 continue
 
-            try:
-                module_cls = __module_loader__(path)
-                self._logger.debug(f"Loading module {name} from {path}")
-                params = config.get(name, {})
-                self._logger.debug(
-                    f"Module {name} config params: {list(params.keys())}"
-                )
-                # params["logger"] = self._logger
-                # params["serializer"] = self._serializer
-                module_instance = module_cls(**params)
-                self.__setattr__(name, module_instance)
-                self._logger.debug(f"Module {name} initialized successfully")
-
-            except Exception as e:
-                self._logger.error(
-                    f"Failed to load module {name} from {path}: {e}",
-                    exc_info=True,
-                )
+            if isinstance(path, dict):
+                subconfig = config.get(name, {})
+                if not isinstance(subconfig, dict):
+                    subconfig = {}
+
+                for subname, subpath in path.items():
+                    if subname not in subconfig:
+                        self._logger.debug(
+                            f"Missing configuration for module {name}.{subname}"
+                        )
+                        continue
+
+                    try:
+                        module_cls = __module_loader__(subpath)
+                        self._logger.debug(
+                            f"Loading module {name}.{subname} from {subpath}"
+                        )
+                        params = subconfig.get(subname, {})
+                        self._logger.debug(
+                            f"Module {name}.{subname} config params: {list(params.keys())}"
+                        )
+                        module_instance = module_cls(**params)
+
+                        if self.jose is None:
+                            self.jose = {}
+                        self.jose[subname] = module_instance
+
+                        if subname == "jwt":
+                            self.jwt = module_instance
+                        elif subname == "jws":
+                            self.jws = module_instance
+                        elif subname == "jwe":
+                            self.jwe = module_instance
+
+                        self._logger.debug(
+                            f"Module {name}.{subname} initialized successfully"
+                        )
+
+                    except Exception as e:
+                        self._logger.error(
+                            f"Failed to load module {name}.{subname} from {subpath}: {e}",
+                            exc_info=True,
+                        )
+            else:
+                try:
+                    module_cls = __module_loader__(path)
+                    self._logger.debug(f"Loading module {name} from {path}")
+                    params = config.get(name, {})
+                    self._logger.debug(
+                        f"Module {name} config params: {list(params.keys())}"
+                    )
+                    module_instance = module_cls(**params)
+                    self.__setattr__(name, module_instance)
+                    self._logger.debug(
+                        f"Module {name} initialized successfully"
+                    )
+
+                except Exception as e:
+                    self._logger.error(
+                        f"Failed to load module {name} from {path}: {e}",
+                        exc_info=True,
+                    )
 
     def __otp(
         self, type: Literal["totp", "hotp"] | None = None
@@ -188,6 +248,40 @@ class BaseJam(ABC):
             case _:
                 raise JamConfigurationError(message="Unknown OTP type.")
 
+    def __setup_plugins(self, plugins: list[type[BasePlugin]]) -> None:
+        """Setup plugins."""
+        for plugin in plugins:
+            self._logger.debug(f"Setup plugin: {plugin.name}")
+            from jam.utils.version_check import __is_compatible__
+
+            if not __is_compatible__(None, plugin.jam_requires):
+                continue
+
+            _plugin = plugin(self)
+            _plugin.setup()
+            self._plugins.append(_plugin)
+
+    def emit(self, event: str, **kwargs) -> Any:
+        """Emit event.
+
+        Args:
+            event (str): Event name,
+            **kwargs: Event data
+        """
+        for plugin in self._plugins:
+            handler = getattr(plugin, f"on_{event}", None)
+
+            if handler:
+                try:
+                    result = handler(**kwargs)
+                    if isinstance(result, dict):
+                        kwargs.update(result)
+
+                except Exception as e:
+                    self._logger.error(f"Plugin:{plugin.name} | error: {e}")
+
+        return kwargs
+
     @abstractmethod
     def jwt_encode(
         self,
@@ -196,6 +290,7 @@ class BaseJam(ABC):
         aud: str | None = None,
         exp: int | None = None,
         nbf: int | None = None,
+        jti: str | None = None,
         *,
         payload: dict[str, Any] | None = None,
         header: dict[str, Any] | None = None,
@@ -208,6 +303,7 @@ class BaseJam(ABC):
             iss (str | None): The issuer.
             sub (str | None): The subject.
             aud (str | None): The audience.
+            jti (str | None): The JWT ID. If none use the JTI fabric function.
             header (dict[str, Any] | None): The header to include in the JWT.
             payload (dict[str, Any] | None): The payload to include in the JWT.
 
@@ -240,6 +336,70 @@ class BaseJam(ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    def jws_sign(
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Sign data using JWS.
+
+        Args:
+            data: Data to sign. If dict, will be JSON encoded.
+            header: JWS header.
+
+        Returns:
+            str: JWS token.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def jws_verify(self, token: str) -> dict[str, Any]:
+        """Verify JWS token.
+
+        Args:
+            token: JWS token.
+
+        Returns:
+            dict[str, Any]: Decoded payload.
+
+        Raises:
+            JamJWSVerificationError: If verification fails.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def jwe_encrypt(
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encrypt data using JWE.
+
+        Args:
+            data: Data to encrypt. If dict, will be JSON encoded.
+            header: JWE header.
+
+        Returns:
+            str: JWE token.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def jwe_decrypt(self, token: str) -> bytes:
+        """Decrypt JWE token.
+
+        Args:
+            token: JWE token.
+
+        Returns:
+            bytes: Decrypted data.
+
+        Raises:
+            JamJWEDecryptionError: If decryption fails.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     def session_create(self, session_key: str, data: dict[str, Any]) -> str:
         """Create new session.

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/src/jam/__init__.py

@@ -7,10 +7,8 @@ Documentation: https://jam.makridenko.ru
 """
 
 from jam.__base__ import BaseJam
-from jam.__base_encoder__ import BaseEncoder
-from jam.encoders import JsonEncoder
 from jam.instance import Jam
 
 
-__version__ = "3.2.0b2"
-__all__ = ["Jam", "JsonEncoder", "BaseJam", "BaseEncoder"]
+__version__ = "3.2.0rc0"
+__all__ = ["Jam", "BaseJam"]

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/src/jam/aio/__base__.py

@@ -6,15 +6,19 @@ from typing import Any
 from jam.__base__ import BaseJam
 from jam.aio.oauth2.__base__ import BaseAsyncOAuth2Client
 from jam.aio.sessions.__base__ import BaseAsyncSessionModule
+from jam.jose.__base__ import BaseJWE, BaseJWS
 
 
 class BaseAsyncJam(BaseJam):
     """Base async jam instance."""
 
-    MODULES: dict[str, str] = {}
+    MODULES: dict[str, str | dict[str, str]] = {}
 
     session: BaseAsyncSessionModule | None = None  # type: ignore[override]
     oauth2: dict[str, BaseAsyncOAuth2Client] | None = None  # type: ignore[override]
+    jose: dict[str, Any] | None = None  # type: ignore[override]
+    jws: BaseJWS | None = None  # type: ignore[override]
+    jwe: BaseJWE | None = None  # type: ignore[override]
 
     @abstractmethod
     async def jwt_make_payload(  # type: ignore[override]
@@ -46,13 +50,14 @@ class BaseAsyncJam(BaseJam):
         raise NotImplementedError
 
     @abstractmethod
-    async def jwt_encode(
+    async def jwt_encode(  # type: ignore[override]
         self,
         iss: str | None = None,
         sub: str | None = None,
         aud: str | None = None,
         exp: int | None = None,
         nbf: int | None = None,
+        jti: str | None = None,
         *,
         payload: dict[str, Any] | None = None,
         header: dict[str, Any] | None = None,
@@ -65,6 +70,7 @@ class BaseAsyncJam(BaseJam):
             iss (str | None): The issuer.
             sub (str | None): The subject.
             aud (str | None): The audience.
+            jti (str | None): The JWT ID. If none use the JTI fabric function.
             header (dict[str, Any] | None): The header to include in the JWT.
             payload (dict[str, Any] | None): The payload to include in the JWT.
 
@@ -340,6 +346,74 @@ class BaseAsyncJam(BaseJam):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def jws_sign(  # type: ignore[override]
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Sign data using JWS.
+
+        Args:
+            data: Data to sign. If dict, will be JSON encoded.
+            header: JWS header.
+
+        Returns:
+            str: JWS token.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def jws_verify(  # type: ignore[override]
+        self, token: str
+    ) -> dict[str, Any]:
+        """Verify JWS token.
+
+        Args:
+            token: JWS token.
+
+        Returns:
+            dict[str, Any]: Decoded payload.
+
+        Raises:
+            JamJWSVerificationError: If verification fails.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def jwe_encrypt(  # type: ignore[override]
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encrypt data using JWE.
+
+        Args:
+            data: Data to encrypt. If dict, will be JSON encoded.
+            header: JWE header.
+
+        Returns:
+            str: JWE token.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def jwe_decrypt(  # type: ignore[override]
+        self, token: str
+    ) -> bytes:
+        """Decrypt JWE token.
+
+        Args:
+            token: JWE token.
+
+        Returns:
+            bytes: Decrypted data.
+
+        Raises:
+            JamJWEDecryptionError: If decryption fails.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     async def paseto_decode(  # type: ignore[override]
         self, token: str, check_exp: bool = True, check_list: bool = True

{jamlib-3.2.0b2 → jamlib-3.2.0rc0}/src/jam/aio/instance.py

@@ -18,8 +18,12 @@ from jam.exceptions import (
 class Jam(BaseAsyncJam):
     """Main async Jam instance."""
 
-    MODULES: dict[str, str] = {
-        "jwt": "jam.aio.jwt.create_instance",
+    MODULES: dict[str, str | dict[str, str]] = {
+        "jose": {
+            "jwt": "jam.jose.create_jwt_instance",
+            "jws": "jam.jose.create_jws_instance",
+            "jwe": "jam.jose.create_jwe_instance",
+        },
         "session": "jam.aio.sessions.create_instance",
         "oauth2": "jam.aio.oauth2.create_instance",
         "paseto": "jam.paseto.create_instance",
@@ -77,6 +81,7 @@ class Jam(BaseAsyncJam):
         aud: str | None = None,
         exp: int | None = None,
         nbf: int | None = None,
+        jti: str | None = None,
         *,
         payload: dict[str, Any] | None = None,
         header: dict[str, Any] | None = None,
@@ -89,6 +94,7 @@ class Jam(BaseAsyncJam):
             iss (str | None): The issuer.
             sub (str | None): The subject.
             aud (str | None): The audience.
+            jti (str | None): The JWT ID. If none use the JTI fabric function.
             header (dict[str, Any] | None): The header to include in the JWT.
             payload (dict[str, Any] | None): The payload to include in the JWT.
 
@@ -96,12 +102,15 @@ class Jam(BaseAsyncJam):
             str: The encoded JWT.
         """
         assert self.jwt is not None
+        if not jti:
+            jti = self.jwt.jti
         token = self.jwt.encode(
             iss=iss,
             sub=sub,
             aud=aud,
             exp=exp,
             nbf=nbf,
+            jti=jti,
             payload=payload,
             header=header,
         )
@@ -184,6 +193,76 @@ class Jam(BaseAsyncJam):
             return {"header": headers, "payload": payload}
         return payload
 
+    async def jws_sign(
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Sign data using JWS.
+
+        Args:
+            data: Data to sign. If dict, will be JSON encoded.
+            header: JWS header.
+
+        Returns:
+            str: JWS token.
+        """
+        assert self.jws is not None
+        self._logger.debug(f"Signing data with JWS, header: {header}")
+        token = self.jws.sign(header or {}, data)
+        self._logger.debug(f"JWS token created, length: {len(token)}")
+        return token
+
+    async def jws_verify(self, token: str) -> dict[str, Any]:
+        """Verify JWS token.
+
+        Args:
+            token: JWS token.
+
+        Returns:
+            dict[str, Any]: Decoded payload.
+        """
+        assert self.jws is not None
+        self._logger.debug(f"Verifying JWS token, length: {len(token)}")
+        result = self.jws.verify(token)
+        self._logger.debug("JWS token verified successfully")
+        return result
+
+    async def jwe_encrypt(
+        self,
+        data: dict[str, Any] | str,
+        header: dict[str, Any] | None = None,
+    ) -> str:
+        """Encrypt data using JWE.
+
+        Args:
+            data: Data to encrypt. If dict, will be JSON encoded.
+            header: JWE header.
+
+        Returns:
+            str: JWE token.
+        """
+        assert self.jwe is not None
+        self._logger.debug(f"Encrypting data with JWE, header: {header}")
+        token = self.jwe.encrypt(data, header)
+        self._logger.debug(f"JWE token created, length: {len(token)}")
+        return token
+
+    async def jwe_decrypt(self, token: str) -> bytes:
+        """Decrypt JWE token.
+
+        Args:
+            token: JWE token.
+
+        Returns:
+            bytes: Decrypted data.
+        """
+        assert self.jwe is not None
+        self._logger.debug(f"Decrypting JWE token, length: {len(token)}")
+        result = self.jwe.decrypt(token)
+        self._logger.debug("JWE token decrypted successfully")
+        return result
+
     async def session_create(
         self, session_key: str, data: dict[str, Any]
     ) -> str: