python-neva 0.3.1__tar.gz → 0.4.0__tar.gz

{python_neva-0.3.1 → python_neva-0.4.0}/.gitignore

@@ -9,9 +9,6 @@ wheels/
 # Virtual environments
 .venv
 
-# Mypy
-.mypy_cache/
-
 # Tests / Coverage / Benchmarks
 htmlcov/
 .coverage

{python_neva-0.3.1 → python_neva-0.4.0}/.pre-commit-config.yaml

@@ -21,6 +21,6 @@ repos:
     hooks:
       - id: ty
         name: ty check
-        entry: ty check . --project bloom
-        files: ^bloom/
+        entry: ty check . --project neva
+        files: ^neva/
         language: system

{python_neva-0.3.1 → python_neva-0.4.0}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: python-neva
-Version: 0.3.1
+Version: 0.4.0
 Summary: Add your description here
 Requires-Python: >=3.12
+Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.7.2
 Requires-Dist: fastapi[all]>=0.124.0
 Requires-Dist: flexmock>=0.13.0
+Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pyinstrument>=5.1.1
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: tortoise-orm[accel]>=0.25.3

{python_neva-0.3.1 → python_neva-0.4.0}/neva/arch/facade.py

@@ -134,15 +134,6 @@ class Facade(ABC, metaclass=FacadeMeta):
     Facades provide a convenient static interface to services bound in the
     application's dependency injection container. Each facade must implement
     get_facade_accessor to specify which service it represents.
-
-    Example:
-        class Config(Facade):
-            @classmethod
-            def get_facade_accessor(cls) -> str:
-                return "config"
-
-        # Now you can use: Config.get("app.name")
-
     """
 
     _app: ClassVar["Application | None"]

python_neva-0.4.0/neva/security/__init__.py

@@ -0,0 +1,16 @@
+"""Security module for authentication and hashing."""
+
+from neva.security.encryption import AesEncrypter, DecryptionError, Encrypter
+from neva.security.hashing import Argon2Hasher, BcryptHasher, HashManager, Hasher
+from neva.security.provider import SecurityProvider
+
+__all__ = [
+    "AesEncrypter",
+    "Argon2Hasher",
+    "BcryptHasher",
+    "DecryptionError",
+    "Encrypter",
+    "HashManager",
+    "Hasher",
+    "SecurityProvider",
+]

python_neva-0.4.0/neva/security/encryption/__init__.py

@@ -0,0 +1,11 @@
+"""Encryption module for symmetric encryption."""
+
+from neva.security.encryption.encrypter import AesEncrypter, DecryptionError
+from neva.security.encryption.protocol import Encrypter, JsonValue
+
+__all__ = [
+    "AesEncrypter",
+    "DecryptionError",
+    "Encrypter",
+    "JsonValue",
+]

python_neva-0.4.0/neva/security/encryption/encrypter.py

@@ -0,0 +1,171 @@
+"""Encryption service using AES-256-GCM."""
+
+import base64
+import binascii
+import json
+import os
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from neva import Err, Ok, Result
+from neva.arch import Application
+from neva.config import ConfigRepository
+from neva.security.encryption.protocol import JsonValue
+
+
+class DecryptionError(Exception):
+    """Raised when decryption fails."""
+
+
+class AesEncrypter:
+    """Encryption service using AES-256-GCM."""
+
+    def __init__(self, app: Application) -> None:
+        """Initialize the encrypter.
+
+        Keys are loaded lazily on first encrypt/decrypt call to avoid
+        re-entering the DI container during construction.
+
+        Args:
+            app: The application instance for configuration access.
+        """
+        self._app: Application = app
+        self._ciphers: list[AESGCM] | None = None
+
+    @staticmethod
+    def generate_key() -> str:
+        """Generate a 32-bytes encryption key.
+
+        Returns:
+            A base64-encoded 32-byte key suitable for AES-256.
+        """
+        return base64.b64encode(os.urandom(32)).decode()
+
+    def encrypt(self, value: JsonValue) -> Result[str, str]:
+        """Encrypt a value.
+
+        Args:
+            value: The value to encrypt. Non-string values are JSON serialized.
+
+        Returns:
+            Ok with base64-encoded encrypted payload, or Err with message.
+        """
+        if isinstance(value, str):
+            wrapper = {"__str__": value}
+        else:
+            wrapper = {"__json__": value}
+
+        try:
+            payload = json.dumps(wrapper)
+        except (TypeError, ValueError) as e:
+            return Err(f"Failed to serialize value: {e}")
+
+        plaintext = payload.encode("utf-8")
+        iv = os.urandom(12)
+
+        ciphers = self._get_ciphers()
+        ciphertext = ciphers[0].encrypt(iv, plaintext, None)
+
+        encrypted_payload = json.dumps(
+            {
+                "iv": base64.b64encode(iv).decode("ascii"),
+                "value": base64.b64encode(ciphertext).decode("ascii"),
+            }
+        )
+
+        return Ok(base64.b64encode(encrypted_payload.encode("utf-8")).decode("ascii"))
+
+    def decrypt(self, payload: str) -> Result[JsonValue, str]:
+        """Decrypt a payload.
+
+        Args:
+            payload: Base64-encoded encrypted payload.
+
+        Returns:
+            Ok with the decrypted value, or Err with message.
+        """
+        try:
+            encrypted_data = json.loads(base64.b64decode(payload))
+            iv = base64.b64decode(encrypted_data["iv"])
+            ciphertext = base64.b64decode(encrypted_data["value"])
+        except (json.JSONDecodeError, KeyError, binascii.Error) as e:
+            return Err(f"Invalid encrypted payload format: {e}")
+
+        for cipher in self._get_ciphers():
+            try:
+                plaintext = cipher.decrypt(iv, ciphertext, None)
+                break
+            except InvalidTag:
+                continue
+        else:
+            return Err("Decryption failed: invalid key or corrupted data")
+
+        try:
+            data = json.loads(plaintext.decode("utf-8"))
+            if "__str__" in data:
+                return Ok(data["__str__"])
+            return Ok(data["__json__"])
+        except (json.JSONDecodeError, KeyError) as e:
+            return Err(f"Decryption failed: invalid payload structure: {e}")
+
+    def _get_ciphers(self) -> list[AESGCM]:
+        """Return cached ciphers, loading keys on first access.
+
+        Returns:
+            List of AESGCM cipher instances.
+        """
+        if self._ciphers is None:
+            self._ciphers = self._load_keys()
+        return self._ciphers
+
+    def _load_keys(self) -> list[AESGCM]:
+        """Load encryption keys from configuration.
+
+        Returns:
+            List of AESGCM cipher instances.
+
+        Raises:
+            ValueError: If no encryption key is configured.
+        """
+        config = self._app.make(ConfigRepository).expect(
+            "ConfigRepository not found in container"
+        )
+
+        key = config.get("app.key", default=None).unwrap_or(None)
+        previous_keys = config.get("app.previous_keys", default=[]).unwrap_or([])
+
+        if key is None:
+            msg = "No encryption key configured. Set 'app.key' in configuration."
+            raise ValueError(msg)
+
+        ciphers = [AESGCM(self._parse_key(key))]
+
+        for prev_key in previous_keys:
+            ciphers.append(AESGCM(self._parse_key(prev_key)))
+
+        return ciphers
+
+    def _parse_key(self, key: str) -> bytes:
+        """Parse a base64-encoded key into bytes.
+
+        Args:
+            key: Base64-encoded 32-byte key.
+
+        Returns:
+            The decoded key bytes.
+
+        Raises:
+            ValueError: If key is not valid base64 or not 32 bytes.
+        """
+        try:
+            key_bytes = base64.b64decode(key)
+        except binascii.Error as e:
+            msg = "Invalid encryption key: must be valid base64"
+            raise ValueError(msg) from e
+
+        if len(key_bytes) != 32:
+            msg = f"Invalid encryption key: must be 32 bytes, got {len(key_bytes)}"
+            raise ValueError(msg)
+
+        return key_bytes

python_neva-0.4.0/neva/security/encryption/protocol.py

@@ -0,0 +1,34 @@
+"""Encrypter protocol."""
+
+from typing import Any, Protocol, runtime_checkable
+
+from neva import Result
+
+JsonValue = str | int | float | bool | list[Any] | dict[str, Any] | None
+
+
+@runtime_checkable
+class Encrypter(Protocol):
+    """Symmetric encryption interface."""
+
+    def encrypt(self, value: JsonValue) -> Result[str, str]:
+        """Encrypt a value.
+
+        Args:
+            value: The value to encrypt. Non-string values are JSON serialized.
+
+        Returns:
+            Ok with base64-encoded encrypted payload, or Err with message.
+        """
+        ...
+
+    def decrypt(self, payload: str) -> Result[JsonValue, str]:
+        """Decrypt a payload.
+
+        Args:
+            payload: Base64-encoded encrypted payload.
+
+        Returns:
+            Ok with the decrypted value, or Err with message.
+        """
+        ...

python_neva-0.4.0/neva/security/hashing/__init__.py

@@ -0,0 +1,13 @@
+"""Hashing module for password hashing."""
+
+from neva.security.hashing.hash_manager import HashManager
+from neva.security.hashing.hashers.argon2 import Argon2Hasher
+from neva.security.hashing.hashers.bcrypt import BcryptHasher
+from neva.security.hashing.hashers.protocol import Hasher
+
+__all__ = [
+    "Argon2Hasher",
+    "BcryptHasher",
+    "HashManager",
+    "Hasher",
+]

python_neva-0.4.0/neva/security/hashing/config.py

@@ -0,0 +1,28 @@
+"""Hashing module config."""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+class BcryptConfig(TypedDict):
+    """Bcrypt hasher config."""
+
+    rounds: int
+    prefix: str
+
+
+class Argon2Config(TypedDict):
+    """Argon2 hasher config."""
+
+    time_cost: int
+    memory_cost: int
+    parallelism: int
+    hash_len: int
+    salt_len: int
+
+
+class HashingConfig(TypedDict):
+    """Hasher config."""
+
+    driver: Literal["argon2", "bcrypt"]
+    argon: NotRequired[Argon2Config]
+    bcrypt: NotRequired[BcryptConfig]

python_neva-0.4.0/neva/security/hashing/hash_manager.py

@@ -0,0 +1,146 @@
+"""Hash manager for managing password hashing strategies."""
+
+from typing import override
+
+from neva import Option, from_optional
+from neva.arch import Application
+from neva.config import ConfigRepository
+from neva.security.hashing.hashers.argon2 import Argon2Hasher
+from neva.security.hashing.hashers.bcrypt import BcryptHasher
+from neva.security.hashing.hashers.protocol import Hasher
+from neva.support.strategy import StrategyResolver
+
+
+class HashManager(StrategyResolver[Hasher]):
+    """Manager for password hashing strategies."""
+
+    def __init__(self, app: Application) -> None:
+        """Initialize the hash manager and register available hashers.
+
+        Args:
+            app: The application instance for configuration access.
+        """
+        super().__init__(app)
+
+        self.register("argon2", self._create_argon2_hasher)
+        self.register("bcrypt", self._create_bcrypt_hasher)
+
+    @override
+    def default(self) -> Option[str]:
+        """Get the default hasher from configuration.
+
+        Returns:
+            Option containing the default hasher name ("argon2" or "bcrypt").
+        """
+        config_result = self.app.make(ConfigRepository)
+        if config_result.is_err:
+            return from_optional(None)
+
+        config = config_result.unwrap()
+        driver = config.get("hashing.driver", default=None).unwrap_or(None)
+        return from_optional(driver)
+
+    def make(
+        self,
+        plaintext: str | bytes,
+        *,
+        salt: bytes | None = None,
+        hasher: str | None = None,
+    ) -> str:
+        """Hash a plaintext password using the specified or default hasher.
+
+        Args:
+            plaintext: The password to hash.
+            salt: Optional salt for the hash.
+            hasher: Name of the hasher to use (defaults to configured hasher).
+
+        Returns:
+            The hashed password string.
+        """
+        hasher_instance = self.use(hasher).expect(
+            f"Failed to resolve hasher '{hasher or 'default'}'"
+        )
+        return hasher_instance.make(plaintext, salt=salt)
+
+    def check(
+        self,
+        plaintext: str | bytes,
+        hashed: str | bytes,
+        *,
+        hasher: str | None = None,
+    ) -> bool:
+        """Verify a password against a hashed value.
+
+        Args:
+            plaintext: The plaintext password to verify.
+            hashed: The hashed password to verify against.
+            hasher: Name of the hasher to use (defaults to configured hasher).
+
+        Returns:
+            True if the password matches, False otherwise.
+        """
+        hasher_instance = self.use(hasher).expect(
+            f"Failed to resolve hasher '{hasher or 'default'}'"
+        )
+        return hasher_instance.check(plaintext, hashed)
+
+    def needs_rehash(
+        self,
+        hashed: str | bytes,
+        *,
+        hasher: str | None = None,
+    ) -> bool:
+        """Check if a hashed password needs to be rehashed.
+
+        Args:
+            hashed: The hashed password to check.
+            hasher: Name of the hasher to use (defaults to configured hasher).
+
+        Returns:
+            True if the password needs rehashing, False otherwise.
+        """
+        hasher_instance = self.use(hasher).expect(
+            f"Failed to resolve hasher '{hasher or 'default'}'"
+        )
+        return hasher_instance.needs_rehash(hashed)
+
+    def _create_argon2_hasher(self, manager: StrategyResolver[Hasher]) -> Argon2Hasher:
+        """Create an instance of the Argon2 hash strategy.
+
+        Args:
+            manager: The strategy resolver instance.
+
+        Returns:
+            Configured Argon2Hasher instance.
+        """
+        config = manager.app.make(ConfigRepository).unwrap()
+        argon_config = config.get("hashing.argon", default={}).unwrap()
+
+        if isinstance(argon_config, dict):
+            return Argon2Hasher(
+                time_cost=argon_config.get("time_cost", 2),
+                memory_cost=argon_config.get("memory_cost", 102400),
+                parallelism=argon_config.get("parallelism", 8),
+                hash_len=argon_config.get("hash_len", 16),
+                salt_len=argon_config.get("salt_len", 16),
+            )
+        return Argon2Hasher()
+
+    def _create_bcrypt_hasher(self, manager: StrategyResolver[Hasher]) -> BcryptHasher:
+        """Create an instance of the Bcrypt hash strategy.
+
+        Args:
+            manager: The strategy resolver instance.
+
+        Returns:
+            Configured BcryptHasher instance.
+        """
+        config = manager.app.make(ConfigRepository).unwrap()
+        bcrypt_config = config.get("hashing.bcrypt", default={}).unwrap()
+
+        if isinstance(bcrypt_config, dict):
+            return BcryptHasher(
+                rounds=bcrypt_config.get("rounds", 12),
+                prefix=bcrypt_config.get("prefix", "2b"),
+            )
+        return BcryptHasher()

python_neva-0.4.0/neva/security/hashing/hashers/__init__.py

@@ -0,0 +1 @@
+"""Hasher protocol and built-in hashers."""

python_neva-0.4.0/neva/security/hashing/hashers/argon2.py

@@ -0,0 +1,59 @@
+"""Argon2 hasher."""
+
+from typing import override
+
+import argon2
+from pwdlib.hashers.argon2 import Argon2Hasher as PwdLibArgon2Hasher
+
+from neva.security.hashing.hashers.protocol import Hasher
+
+
+class Argon2Hasher(Hasher):
+    """Argon2 hasher."""
+
+    def __init__(
+        self,
+        time_cost: int = argon2.DEFAULT_TIME_COST,
+        memory_cost: int = argon2.DEFAULT_MEMORY_COST,
+        parallelism: int = argon2.DEFAULT_PARALLELISM,
+        hash_len: int = argon2.DEFAULT_HASH_LENGTH,
+        salt_len: int = argon2.DEFAULT_RANDOM_SALT_LENGTH,
+    ) -> None:
+        """Initialize the hasher."""
+        self._hasher: PwdLibArgon2Hasher = PwdLibArgon2Hasher(
+            time_cost,
+            memory_cost,
+            parallelism,
+            hash_len,
+            salt_len,
+        )
+
+    @override
+    def make(
+        self,
+        plaintext: str | bytes,
+        *,
+        salt: bytes | None = None,
+    ) -> str:
+        return self._hasher.hash(
+            password=plaintext,
+            salt=salt,
+        )
+
+    @override
+    def check(
+        self,
+        plaintext: str | bytes,
+        hashed: str | bytes,
+    ) -> bool:
+        return self._hasher.verify(
+            password=plaintext,
+            hash=hashed,
+        )
+
+    @override
+    def needs_rehash(
+        self,
+        hashed: str | bytes,
+    ) -> bool:
+        return self._hasher.check_needs_rehash(hashed)

python_neva-0.4.0/neva/security/hashing/hashers/bcrypt.py

@@ -0,0 +1,49 @@
+"""Bcrypt hasher."""
+
+from typing import Literal, override
+
+from pwdlib.hashers.bcrypt import BcryptHasher as PwdLibBcryptHasher
+
+from neva.security.hashing.hashers.protocol import Hasher
+
+
+class BcryptHasher(Hasher):
+    """Bcrypt hasher."""
+
+    def __init__(
+        self,
+        rounds: int = 12,
+        prefix: Literal["2a", "2b"] = "2a",
+    ) -> None:
+        """Initialize the hasher."""
+        self._hasher: PwdLibBcryptHasher = PwdLibBcryptHasher(rounds, prefix)
+
+    @override
+    def make(
+        self,
+        plaintext: str | bytes,
+        *,
+        salt: bytes | None = None,
+    ) -> str:
+        return self._hasher.hash(
+            password=plaintext,
+            salt=salt,
+        )
+
+    @override
+    def check(
+        self,
+        plaintext: str | bytes,
+        hashed: str | bytes,
+    ) -> bool:
+        return self._hasher.verify(
+            password=plaintext,
+            hash=hashed,
+        )
+
+    @override
+    def needs_rehash(
+        self,
+        hashed: str | bytes,
+    ) -> bool:
+        return self._hasher.check_needs_rehash(hashed)

python_neva-0.4.0/neva/security/hashing/hashers/protocol.py

@@ -0,0 +1,31 @@
+"""Hasher protocol."""
+
+from typing import Protocol
+
+
+class Hasher(Protocol):
+    """Wrapper hasher class."""
+
+    def make(
+        self,
+        plaintext: str | bytes,
+        *,
+        salt: bytes | None = None,
+    ) -> str:
+        """Hash a plaintext password."""
+        ...
+
+    def check(
+        self,
+        plaintext: str | bytes,
+        hashed: str | bytes,
+    ) -> bool:
+        """Verify a password against a hashed value."""
+        ...
+
+    def needs_rehash(
+        self,
+        hashed: str | bytes,
+    ) -> bool:
+        """Check if a hashed value needs to be rehashed."""
+        ...

python_neva-0.4.0/neva/security/provider.py

@@ -0,0 +1,17 @@
+"""Security service provider."""
+
+from typing import Self, override
+
+from neva import Ok, Result, arch
+from neva.security.encryption import AesEncrypter, Encrypter
+from neva.security.hashing import HashManager
+
+
+class SecurityProvider(arch.ServiceProvider):
+    """Provider for security features."""
+
+    @override
+    def register(self) -> Result[Self, str]:
+        self.app.bind(HashManager, interface=HashManager)
+        self.app.bind(AesEncrypter, interface=Encrypter)
+        return Ok(self)

{python_neva-0.3.1 → python_neva-0.4.0}/neva/support/accessors.py

@@ -21,12 +21,6 @@ def get_attr(obj: object, name: str) -> Result[Any, str]:
 
     Returns:
         Result containing the attribute value or an error message if not found.
-
-    Example:
-        result = get_attr(my_object, "my_attribute")
-        if result.is_ok:
-            value = result.unwrap()
-
     """
     if hasattr(obj, name):
         return Ok(getattr(obj, name))

{python_neva-0.3.1 → python_neva-0.4.0}/neva/support/facade/__init__.py

@@ -2,10 +2,14 @@
 
 from neva.support.facade.app import App
 from neva.support.facade.config import Config
+from neva.support.facade.crypt import Crypt
+from neva.support.facade.hash import Hash
 from neva.support.facade.log import Log
 
 __all__ = [
     "App",
     "Config",
+    "Crypt",
+    "Hash",
     "Log",
 ]

python_neva-0.4.0/neva/support/facade/crypt.py

@@ -0,0 +1,15 @@
+"""Encryption utility facade."""
+
+from typing import override
+
+from neva.arch import Facade
+from neva.security.encryption import Encrypter
+
+
+class Crypt(Facade):
+    """Encryption utility facade."""
+
+    @classmethod
+    @override
+    def get_facade_accessor(cls) -> type:
+        return Encrypter