jpassende 1.0.0__py3-none-any.whl

jpassende/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+from ._version import __version__
+from .enums import SecurityLayer, PatternCategory
+from .exceptions import InvalidPackageError
+from .datatypes import CryptoResult, DecodeResult
+from .core import JPassende
+
+__all__ = [
+    "__version__",
+    "SecurityLayer",
+    "PatternCategory",
+    "InvalidPackageError",
+    "CryptoResult",
+    "DecodeResult",
+    "JPassende",
+]

jpassende/_version.py

@@ -0,0 +1,3 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+__version__ = "1.0.0"

jpassende/core.py

@@ -0,0 +1,274 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import base64
+import hmac
+import struct
+import time
+import logging
+import threading
+from collections import OrderedDict
+from typing import Union, Optional, List, Tuple
+
+from Crypto.Protocol.KDF import PBKDF2, HKDF
+from Crypto.Hash import SHA512, SHA256
+
+from ._version import __version__
+from .enums import SecurityLayer, PatternCategory
+from .exceptions import InvalidPackageError
+from .datatypes import CryptoResult, DecodeResult
+from . import utils
+
+from .mixins.aead import AeadMixin
+from .mixins.stream import StreamMixin
+from .mixins.block import BlockMixin
+from .mixins.derivation import DerivationMixin
+
+logger = logging.getLogger(__name__)
+
+
+class JPassende(AeadMixin, StreamMixin, BlockMixin, DerivationMixin):
+    PATTERNS = {
+        'vail': {'category': PatternCategory.AEAD},
+        'phnx': {'category': PatternCategory.AEAD},
+        'nixl': {'category': PatternCategory.AEAD},
+        'strx': {'category': PatternCategory.STREAM},
+        'rvrs': {'category': PatternCategory.STREAM},
+        'lfsr': {'category': PatternCategory.STREAM},
+        'aegs': {'category': PatternCategory.BLOCK},
+        'cblk': {'category': PatternCategory.BLOCK},
+        'cfbb': {'category': PatternCategory.BLOCK},
+        'ofbb': {'category': PatternCategory.BLOCK},
+        'hkdf': {'category': PatternCategory.DERIVATION},
+        'scrt': {'category': PatternCategory.DERIVATION},
+        'pbk2': {'category': PatternCategory.DERIVATION},
+        'blk3': {'category': PatternCategory.DERIVATION},
+    }
+    PATTERN_IDS = {
+        'vail': 0, 'phnx': 1, 'nixl': 2, 'strx': 3,
+        'rvrs': 4, 'lfsr': 5, 'aegs': 6, 'cblk': 7,
+        'cfbb': 8, 'ofbb': 9, 'hkdf': 10, 'scrt': 11,
+        'pbk2': 12, 'blk3': 13
+    }
+    PATTERN_INDEX = PATTERN_IDS
+
+    def __init__(self, enable_logging: bool = False):
+        if enable_logging:
+            if not logger.handlers:
+                handler = logging.StreamHandler()
+                formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+                handler.setFormatter(formatter)
+                logger.addHandler(handler)
+                logger.setLevel(logging.DEBUG)
+        else:
+            logger.setLevel(logging.ERROR)
+
+        self._salt_size = 32
+        self._default_nonce = 12
+        self._mac_size = 32
+        self._MAGIC = b'jpas'
+        self._VERSION = 1
+
+        self._derive_cache: OrderedDict = OrderedDict()
+        self._cache_lock = threading.Lock()
+        self._max_cache_entries = 128
+
+        self._encryptors = {
+            'vail': self.vail, 'phnx': self.phnx, 'nixl': self.nixl,
+            'strx': self.strx, 'rvrs': self.rvrs, 'lfsr': self.lfsr,
+            'aegs': self.aegs, 'cblk': self.cblk, 'cfbb': self.cfbb, 'ofbb': self.ofbb,
+            'hkdf': self.hkdf, 'scrt': self.scrt, 'pbk2': self.pbk2, 'blk3': self.blk3,
+        }
+        self._decryptors = {
+            'vail': self.dvail, 'phnx': self.dphnx, 'nixl': self.dnixl,
+            'strx': self.dstrx, 'rvrs': self.drvrs, 'lfsr': self.dlfsr,
+            'aegs': self.daegs, 'cblk': self.dcblk, 'cfbb': self.dcfbb, 'ofbb': self.dofbb,
+            'hkdf': self.dhkdf, 'scrt': self.dscrt, 'pbk2': self.dpbk2, 'blk3': self.dblk3,
+        }
+
+    @staticmethod
+    def _to_bytes(data: Union[str, bytes]) -> bytes:
+        return utils.to_bytes(data)
+
+    @staticmethod
+    def _to_str(data: bytes) -> str:
+        return utils.to_str(data)
+
+    @staticmethod
+    def _secure_bytes(size: int = 32) -> bytes:
+        return utils.secure_bytes(size)
+
+    def _validate_nonempty(self, data: Union[str, bytes], name: str = "data"):
+        utils.validate_nonempty(data, name)
+
+    @staticmethod
+    def _validate_key(key: str, pattern: str = ""):
+        utils.validate_key(key, pattern)
+
+    @staticmethod
+    def _xor_bytes(a: bytes, b: bytes) -> bytes:
+        return utils.xor_bytes(a, b)
+
+    def _mac(self, key: bytes, data: bytes) -> bytes:
+        return utils.mac(key, data)
+
+    def _derive_key(self, password: str, salt: bytes, length: int = 32,
+                    layer: SecurityLayer = SecurityLayer.STANDARD) -> bytes:
+        hash_input = password.encode() + salt + struct.pack('>IB', length, layer.value)
+        cache_key = hashlib.blake2b(hash_input, digest_size=16).digest()
+        with self._cache_lock:
+            if cache_key in self._derive_cache:
+                self._derive_cache.move_to_end(cache_key)
+                logger.debug("Cache hit for key derivation")
+                return self._derive_cache[cache_key]
+        iterations = {
+            SecurityLayer.STANDARD: 300_000,
+            SecurityLayer.FORTIFIED: 600_000,
+            SecurityLayer.QUANTUM: 1_200_000
+        }
+        logger.debug("Deriving key with PBKDF2 (iterations=%d)", iterations[layer])
+        derived = PBKDF2(password.encode(), salt, dkLen=length,
+                         count=iterations[layer], hmac_hash_module=SHA512)
+        with self._cache_lock:
+            if len(self._derive_cache) >= self._max_cache_entries:
+                self._derive_cache.popitem(last=False)
+            self._derive_cache[cache_key] = derived
+        return derived
+
+    def _derive_keys(self, key: str, salt: bytes, layer: SecurityLayer) -> Tuple[bytes, bytes]:
+        base_key = self._derive_key(key, salt, 32, layer)
+        material = HKDF(base_key, 64, salt, SHA256, context=b'jpassende:keys:v2')
+        return material[:32], material[32:]
+
+    def _nonce_size_for(self, pattern: str) -> int:
+        """Return expected nonce size for a given pattern (bytes)."""
+        if pattern in ('vail', 'phnx', 'nixl'):
+            return 12
+        if pattern in ('aegs', 'cblk', 'cfbb', 'ofbb'):
+            return 16
+        if pattern in ('strx', 'rvrs', 'lfsr'):
+            return 16
+        if pattern in ('hkdf', 'scrt', 'pbk2', 'blk3'):
+            return 0
+        return self._default_nonce
+
+    # ---- pack/unpack helpers ----
+    def _pack(self, pattern: str, aad: Optional[bytes], salt: bytes,
+              nonce: bytes, ciphertext: bytes, mac_key: Optional[bytes] = None) -> bytes:
+        pattern_id = self.PATTERN_INDEX[pattern]
+        flags = 0x01 if aad else 0
+        header = self._MAGIC + bytes([self._VERSION, pattern_id, flags])
+        payload = header
+        if aad:
+            aad_block = struct.pack('>I', len(aad)) + aad
+            payload += aad_block
+        body = salt + nonce + ciphertext
+        payload += body
+        if mac_key:
+            payload += self._mac(mac_key, payload)
+        return payload
+
+    def _unpack(self, encoded: bytes, pattern: str) -> Tuple[Optional[bytes], bytes, bytes, bytes, Optional[bytes]]:
+        if len(encoded) < 7:
+            raise InvalidPackageError("  Invalid package – too short for header")
+        if encoded[:4] != self._MAGIC:
+            raise InvalidPackageError("  Invalid magic bytes")
+        if encoded[4] != self._VERSION:
+            raise InvalidPackageError(f"  Unsupported version: {encoded[4]}")
+        if encoded[5] != self.PATTERN_INDEX[pattern]:
+            raise InvalidPackageError("  Pattern mismatch")
+        flags = encoded[6]
+        pos = 7
+        aad = None
+        if flags & 0x01:
+            if len(encoded) < pos + 4:
+                raise InvalidPackageError("  Invalid package – missing AAD length")
+            aad_len = struct.unpack('>I', encoded[pos:pos + 4])[0]
+            pos += 4
+            if len(encoded) < pos + aad_len:
+                raise InvalidPackageError("  Invalid package – truncated AAD")
+            aad = encoded[pos:pos + aad_len]
+            pos += aad_len
+        salt_size = self._salt_size
+        nonce_size = self._nonce_size_for(pattern)
+        mac_size = 0 if pattern in ('vail', 'phnx') else self._mac_size
+        total_body = len(encoded) - pos
+        if total_body < salt_size + nonce_size + mac_size:
+            raise InvalidPackageError("  Invalid package – body too short")
+        salt = encoded[pos:pos + salt_size]
+        pos += salt_size
+        nonce = encoded[pos:pos + nonce_size] if nonce_size > 0 else b''
+        pos += nonce_size
+        ciphertext_len = total_body - salt_size - nonce_size - mac_size
+        ciphertext = encoded[pos:pos + ciphertext_len]
+        pos += ciphertext_len
+        mac_val = encoded[pos:pos + mac_size] if mac_size > 0 else None
+        pos += mac_size if mac_size > 0 else 0
+
+        if pos != len(encoded):
+            raise InvalidPackageError("  Invalid package – trailing data after payload")
+        return aad, salt, nonce, ciphertext, mac_val
+
+    def _pack_derivation(self, pattern: str, aad: Optional[bytes],
+                         salt: bytes, derived_data: bytes, verification: bytes) -> bytes:
+        pattern_id = self.PATTERN_INDEX[pattern]
+        flags = 0x01 if aad else 0
+        header = self._MAGIC + bytes([self._VERSION, pattern_id, flags])
+        aad_block = struct.pack('>I', len(aad)) + aad if aad else b''
+        return header + aad_block + salt + derived_data + verification
+
+    def _unpack_derivation(self, package: bytes, pattern: str) -> Tuple[Optional[bytes], bytes, bytes, bytes]:
+        if package[:4] != self._MAGIC or package[4] != self._VERSION or package[5] != self.PATTERN_INDEX[pattern]:
+            raise InvalidPackageError("  Header mismatch")
+        flags = package[6]
+        pos = 7
+        aad = None
+        if flags & 0x01:
+            if len(package) < pos + 4:
+                raise InvalidPackageError("  Invalid package – missing AAD length")
+            aad_len = struct.unpack('>I', package[pos:pos + 4])[0]
+            pos += 4
+            if len(package) < pos + aad_len:
+                raise InvalidPackageError("  Invalid package – truncated AAD")
+            aad = package[pos:pos + aad_len]
+            pos += aad_len
+        salt = package[pos:pos + self._salt_size]
+        pos += self._salt_size
+        derived = package[pos:-16]
+        verification = package[-16:]
+        if pos + len(derived) + 16 != len(package):
+            raise InvalidPackageError("  Invalid derivation package – trailing data")
+        return aad, salt, derived, verification
+
+    def encode(self, data: Union[str, bytes], pattern: str, key: str = "",
+               layer: SecurityLayer = SecurityLayer.STANDARD,
+               aad: Optional[bytes] = None,
+               output_raw: bool = False, input_raw: bool = False,
+               **kwargs) -> CryptoResult:
+        if pattern not in self.PATTERNS:
+            raise ValueError(f"  Unknown pattern: {pattern}")
+        encryptor = self._encryptors[pattern]
+        t0 = time.perf_counter()
+        encoded = encryptor(data, key, aad=aad, layer=layer,
+                            output_raw=output_raw, input_raw=input_raw, **kwargs)
+        elapsed = time.perf_counter() - t0
+        return CryptoResult(encoded=encoded, pattern=pattern, layer=layer.name,
+                            needs_key=bool(key), elapsed=elapsed)
+
+    def decode(self, encoded: Union[str, bytes], pattern: str, key: str = "",
+               layer: SecurityLayer = SecurityLayer.STANDARD,
+               aad: Optional[bytes] = None,
+               output_raw: bool = False, input_raw: bool = False,
+               **kwargs) -> DecodeResult:
+        if pattern not in self.PATTERNS:
+            raise ValueError(f"  Unknown pattern: {pattern}")
+        decryptor = self._decryptors[pattern]
+        t0 = time.perf_counter()
+        decoded = decryptor(encoded, key, aad=aad, layer=layer,
+                            output_raw=output_raw, input_raw=input_raw, **kwargs)
+        elapsed = time.perf_counter() - t0
+        return DecodeResult(decoded=decoded, pattern=pattern, layer=layer.name,
+                            verified=True, elapsed=elapsed)
+
+    def list_patterns(self) -> List[str]:
+        return list(self.PATTERNS.keys())

jpassende/datatypes.py

@@ -0,0 +1,22 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass, field
+from typing import Union
+import time
+
+@dataclass
+class CryptoResult:
+    encoded: Union[str, bytes]
+    pattern: str
+    layer: str
+    needs_key: bool
+    timestamp: float = field(default_factory=time.time)
+    elapsed: float = 0.0
+
+@dataclass
+class DecodeResult:
+    decoded: Union[str, bytes]
+    pattern: str
+    layer: str
+    verified: bool
+    elapsed: float = 0.0

jpassende/enums.py

@@ -0,0 +1,14 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+from enum import Enum, auto
+
+class SecurityLayer(Enum):
+    STANDARD = auto()
+    FORTIFIED = auto()
+    QUANTUM = auto()
+
+class PatternCategory(Enum):
+    AEAD = auto()
+    STREAM = auto()
+    BLOCK = auto()
+    DERIVATION = auto()

jpassende/exceptions.py

@@ -0,0 +1,4 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+class InvalidPackageError(ValueError):
+    pass

jpassende/mixins/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+# Mixins for jpassende cryptographic patterns

jpassende/mixins/aead.py

@@ -0,0 +1,141 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import base64
+import logging
+from typing import Union, Optional
+from Crypto.Cipher import AES, ChaCha20, ChaCha20_Poly1305
+import hmac
+
+from ..enums import SecurityLayer
+
+logger = logging.getLogger(__name__)
+
+class AeadMixin:
+    def vail(self, data: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+             layer: SecurityLayer = SecurityLayer.STANDARD,
+             output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'vail')
+        salt = self._secure_bytes(self._salt_size)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        nonce = self._secure_bytes(12)
+        cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=nonce)
+        if aad:
+            cipher.update(aad)
+        ct, tag = cipher.encrypt_and_digest(data_bytes)
+        ct_tag = ct + tag
+        package = self._pack('vail', aad, salt, nonce, ct_tag)
+        logger.debug("vail: encrypted %d bytes", len(ct_tag))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dvail(self, encoded: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+              layer: SecurityLayer = SecurityLayer.STANDARD,
+              output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            clean = encoded.strip() if isinstance(encoded, str) else encoded
+            package = clean if isinstance(clean, bytes) else base64.b85decode(clean.encode('utf-8'))
+        self._validate_key(key, 'dvail')
+        aad_pkg, salt, nonce, ct_tag, _ = self._unpack(package, 'vail')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        cipher = AES.new(key_bytes, AES.MODE_GCM, nonce=nonce)
+        if aad_pkg:
+            cipher.update(aad_pkg)
+        try:
+            plain = cipher.decrypt_and_verify(ct_tag[:-16], ct_tag[-16:])
+        except (ValueError, KeyError):
+            raise ValueError("  GCM authentication failed")
+        logger.debug("dvail: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def phnx(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'phnx')
+        salt = self._secure_bytes(self._salt_size)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        nonce = self._secure_bytes(12)
+        cipher = ChaCha20_Poly1305.new(key=key_bytes, nonce=nonce)
+        if aad:
+            cipher.update(aad)
+        ct, tag = cipher.encrypt_and_digest(data_bytes)
+        ct_tag = ct + tag
+        package = self._pack('phnx', aad, salt, nonce, ct_tag)
+        logger.debug("phnx: encrypted %d bytes", len(ct_tag))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dphnx(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            clean = encoded.strip() if isinstance(encoded, str) else encoded
+            package = clean if isinstance(clean, bytes) else base64.b85decode(clean.encode('utf-8'))
+        self._validate_key(key, 'dphnx')
+        aad_pkg, salt, nonce, ct_tag, _ = self._unpack(package, 'phnx')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        cipher = ChaCha20_Poly1305.new(key=key_bytes, nonce=nonce)
+        if aad_pkg:
+            cipher.update(aad_pkg)
+        try:
+            plain = cipher.decrypt_and_verify(ct_tag[:-16], ct_tag[-16:])
+        except (ValueError, KeyError):
+            raise ValueError("  Poly1305 authentication failed")
+        logger.debug("dphnx: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def nixl(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'nixl')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        nonce = self._secure_bytes(12)            # 12 bytes – must match _nonce_size_for
+        cipher = ChaCha20.new(key=enc_key, nonce=nonce)
+        ct = cipher.encrypt(data_bytes)
+        package = self._pack('nixl', aad, salt, nonce, ct, mac_key=mac_key)
+        logger.debug("nixl: encrypted %d bytes", len(ct))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dnixl(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            clean = encoded.strip() if isinstance(encoded, str) else encoded
+            package = clean if isinstance(clean, bytes) else base64.b85decode(clean.encode('utf-8'))
+        self._validate_key(key, 'dnixl')
+        aad_pkg, salt, nonce, ciphertext, mac_val = self._unpack(package, 'nixl')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        cipher = ChaCha20.new(key=enc_key, nonce=nonce)
+        plain = cipher.decrypt(ciphertext)
+        logger.debug("dnixl: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)

jpassende/mixins/block.py

@@ -0,0 +1,171 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import base64
+import logging
+from typing import Union, Optional
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import pad, unpad
+import hmac
+
+from ..enums import SecurityLayer
+
+logger = logging.getLogger(__name__)
+
+class BlockMixin:
+    def aegs(self, data: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+             layer: SecurityLayer = SecurityLayer.STANDARD,
+             output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'aegs')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        iv = self._secure_bytes(16)
+        cipher = AES.new(enc_key, AES.MODE_CTR, nonce=b'', initial_value=iv)
+        padded = pad(data_bytes, AES.block_size)
+        ciphertext = cipher.encrypt(padded)
+        package = self._pack('aegs', aad, salt, iv, ciphertext, mac_key=mac_key)
+        logger.debug("aegs: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b64encode(package).decode('utf-8')
+
+    def daegs(self, encoded: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+              layer: SecurityLayer = SecurityLayer.STANDARD,
+              output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b64decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'daegs')
+        aad_pkg, salt, iv, ciphertext, mac_val = self._unpack(package, 'aegs')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        cipher = AES.new(enc_key, AES.MODE_CTR, nonce=b'', initial_value=iv)
+        padded = cipher.decrypt(ciphertext)
+        plain = unpad(padded, AES.block_size)
+        logger.debug("daegs: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def cblk(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'cblk')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        iv = self._secure_bytes(16)
+        cipher = AES.new(enc_key, AES.MODE_CBC, iv=iv)
+        padded = pad(data_bytes, AES.block_size)
+        ciphertext = cipher.encrypt(padded)
+        package = self._pack('cblk', aad, salt, iv, ciphertext, mac_key=mac_key)
+        logger.debug("cblk: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b64encode(package).decode('utf-8')
+
+    def dcblk(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b64decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dcblk')
+        aad_pkg, salt, iv, ciphertext, mac_val = self._unpack(package, 'cblk')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        cipher = AES.new(enc_key, AES.MODE_CBC, iv=iv)
+        padded = cipher.decrypt(ciphertext)
+        plain = unpad(padded, AES.block_size)
+        logger.debug("dcblk: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def cfbb(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'cfbb')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        iv = self._secure_bytes(16)
+        cipher = AES.new(enc_key, AES.MODE_CFB, iv=iv, segment_size=128)
+        ciphertext = cipher.encrypt(data_bytes)
+        package = self._pack('cfbb', aad, salt, iv, ciphertext, mac_key=mac_key)
+        logger.debug("cfbb: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b64encode(package).decode('utf-8')
+
+    def dcfbb(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b64decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dcfbb')
+        aad_pkg, salt, iv, ciphertext, mac_val = self._unpack(package, 'cfbb')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        cipher = AES.new(enc_key, AES.MODE_CFB, iv=iv, segment_size=128)
+        plain = cipher.decrypt(ciphertext)
+        logger.debug("dcfbb: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def ofbb(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'ofbb')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        iv = self._secure_bytes(16)
+        cipher = AES.new(enc_key, AES.MODE_OFB, iv=iv)
+        ciphertext = cipher.encrypt(data_bytes)
+        package = self._pack('ofbb', aad, salt, iv, ciphertext, mac_key=mac_key)
+        logger.debug("ofbb: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b64encode(package).decode('utf-8')
+
+    def dofbb(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b64decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dofbb')
+        aad_pkg, salt, iv, ciphertext, mac_val = self._unpack(package, 'ofbb')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        cipher = AES.new(enc_key, AES.MODE_OFB, iv=iv)
+        plain = cipher.decrypt(ciphertext)
+        logger.debug("dofbb: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)

jpassende/mixins/derivation.py

@@ -0,0 +1,169 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import hmac
+import base64
+import struct
+import logging
+from typing import Union, Optional
+from Crypto.Protocol.KDF import PBKDF2, scrypt, HKDF
+from Crypto.Hash import SHA512, SHA256
+from ..enums import SecurityLayer
+
+logger = logging.getLogger(__name__)
+
+class DerivationMixin:
+    def hkdf(self, data: Union[str, bytes], key: str, length: int = 64,
+             aad: Optional[bytes] = None, layer: SecurityLayer = SecurityLayer.STANDARD,
+             output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'hkdf')
+        max_len = 255 * hashlib.sha512().digest_size
+        if length > max_len:
+            raise ValueError(f"  Requested HKDF output length ({length}) exceeds maximum allowed ({max_len})")
+        salt = self._secure_bytes(self._salt_size)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        derived = HKDF(data_bytes, length, salt, SHA512, context=b'jpassende:hkdf:v1')
+        verification = hashlib.blake2b(derived + key_bytes, digest_size=16).digest()
+        package = self._pack_derivation('hkdf', aad, salt, derived, verification)
+        logger.debug("hkdf: derived %d bytes", len(derived))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dhkdf(self, encoded, key, length=64, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dhkdf')
+        aad_pkg, salt, derived, verification = self._unpack_derivation(package, 'hkdf')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        expected = hashlib.blake2b(derived + key_bytes, digest_size=16).digest()
+        if not hmac.compare_digest(verification, expected):
+            raise ValueError("  Verification failed")
+        logger.debug("dhkdf: verified %d bytes", len(derived))
+        return derived if output_raw else derived.hex()
+
+    def scrt(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'scrt')
+        salt = self._secure_bytes(self._salt_size)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        n = {SecurityLayer.STANDARD: 2**14, SecurityLayer.FORTIFIED: 2**17, SecurityLayer.QUANTUM: 2**20}[layer]
+        derived = scrypt(data_bytes, salt, key_len=64, N=n, r=8, p=1)
+        verification = hmac.digest(key_bytes, derived, hashlib.sha3_512)[:16]
+        package = self._pack_derivation('scrt', aad, salt, derived, verification)
+        logger.debug("scrt: derived %d bytes", len(derived))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dscrt(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dscrt')
+        aad_pkg, salt, derived, verification = self._unpack_derivation(package, 'scrt')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        expected = hmac.digest(key_bytes, derived, hashlib.sha3_512)[:16]
+        if not hmac.compare_digest(verification, expected):
+            raise ValueError("  Verification failed")
+        logger.debug("dscrt: verified %d bytes", len(derived))
+        return derived if output_raw else derived.hex()
+
+    def pbk2(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'pbk2')
+        salt = self._secure_bytes(self._salt_size)
+        iterations = {SecurityLayer.STANDARD: 300_000, SecurityLayer.FORTIFIED: 600_000,
+                      SecurityLayer.QUANTUM: 1_200_000}[layer]
+        derived = PBKDF2(data_bytes, salt, dkLen=64, count=iterations, hmac_hash_module=SHA512)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        verification = hmac.digest(key_bytes, derived, hashlib.blake2s)[:16]
+        package = self._pack_derivation('pbk2', aad, salt, derived, verification)
+        logger.debug("pbk2: derived %d bytes", len(derived))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dpbk2(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dpbk2')
+        aad_pkg, salt, derived, verification = self._unpack_derivation(package, 'pbk2')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        expected = hmac.digest(key_bytes, derived, hashlib.blake2s)[:16]
+        if not hmac.compare_digest(verification, expected):
+            raise ValueError("  Verification failed")
+        logger.debug("dpbk2: verified %d bytes", len(derived))
+        return derived if output_raw else derived.hex()
+
+    def blk3(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'blk3')
+        salt = self._secure_bytes(self._salt_size)
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        blocks = [data_bytes[i:i+64] for i in range(0, len(data_bytes), 64)]
+        tree = [hashlib.blake2b(block + key_bytes, digest_size=32).digest() for block in blocks]
+        while len(tree) > 1:
+            new_level = []
+            for i in range(0, len(tree), 2):
+                combined = tree[i] + (tree[i+1] if i+1 < len(tree) else tree[i])
+                new_level.append(hashlib.blake2b(combined + key_bytes, digest_size=32).digest())
+            tree = new_level
+        root = tree[0] if tree else hashlib.blake2b(key_bytes, digest_size=32).digest()
+        verification = hmac.digest(key_bytes, root + salt, hashlib.sha3_256)[:16]
+        package = self._pack_derivation('blk3', aad, salt, root, verification)
+        logger.debug("blk3: root commitment %d bytes", len(root))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dblk3(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dblk3')
+        aad_pkg, salt, root, verification = self._unpack_derivation(package, 'blk3')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        key_bytes = self._derive_key(key, salt, 32, layer)
+        expected = hmac.digest(key_bytes, root + salt, hashlib.sha3_256)[:16]
+        if not hmac.compare_digest(verification, expected):
+            raise ValueError("  Verification failed")
+        logger.debug("dblk3: verified root %d bytes", len(root))
+        return root if output_raw else root.hex()

jpassende/mixins/stream.py

@@ -0,0 +1,185 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import base64
+import hmac
+import logging
+from typing import Union, Optional
+from ..enums import SecurityLayer
+
+logger = logging.getLogger(__name__)
+
+class StreamMixin:
+    def strx(self, data: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+             layer: SecurityLayer = SecurityLayer.STANDARD,
+             output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'strx')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        nonce = self._secure_bytes(16)
+        blake2b = hashlib.blake2b
+        xor = self._xor_bytes
+        result = bytearray()
+        counter = 0
+        dlen = len(data_bytes)
+        for i in range(0, dlen, 64):
+            chunk = data_bytes[i:i + 64]
+            keystream = blake2b(nonce + counter.to_bytes(16, 'little'),
+                                key=enc_key, digest_size=64).digest()
+            result.extend(xor(chunk, keystream[:len(chunk)]))
+            counter += 1
+        ciphertext = bytes(result)
+        package = self._pack('strx', aad, salt, nonce, ciphertext, mac_key=mac_key)
+        logger.debug("strx: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dstrx(self, encoded: Union[str, bytes], key: str, aad: Optional[bytes] = None,
+              layer: SecurityLayer = SecurityLayer.STANDARD,
+              output_raw: bool = False, input_raw: bool = False) -> Union[str, bytes]:
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dstrx')
+        aad_pkg, salt, nonce, ciphertext, mac_val = self._unpack(package, 'strx')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        blake2b = hashlib.blake2b
+        xor = self._xor_bytes
+        result = bytearray()
+        counter = 0
+        clen = len(ciphertext)
+        for i in range(0, clen, 64):
+            chunk = ciphertext[i:i + 64]
+            keystream = blake2b(nonce + counter.to_bytes(16, 'little'),
+                                key=enc_key, digest_size=64).digest()
+            result.extend(xor(chunk, keystream[:len(chunk)]))
+            counter += 1
+        plain = bytes(result)
+        logger.debug("dstrx: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def rvrs(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'rvrs')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        nonce = self._secure_bytes(16)
+        block_size = 32
+        sha3 = hashlib.sha3_256
+        xor = self._xor_bytes
+        result = bytearray()
+        prev = nonce
+        dlen = len(data_bytes)
+        for i in range(0, dlen, block_size):
+            chunk = data_bytes[i:i + block_size]
+            keystream = sha3(enc_key + prev).digest()[:len(chunk)]
+            cipher_chunk = xor(chunk, keystream)
+            result.extend(cipher_chunk)
+            prev = cipher_chunk
+        ciphertext = bytes(result)
+        package = self._pack('rvrs', aad, salt, nonce, ciphertext, mac_key=mac_key)
+        logger.debug("rvrs: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def drvrs(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'drvrs')
+        aad_pkg, salt, nonce, ciphertext, mac_val = self._unpack(package, 'rvrs')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        block_size = 32
+        sha3 = hashlib.sha3_256
+        xor = self._xor_bytes
+        result = bytearray()
+        prev = nonce
+        clen = len(ciphertext)
+        for i in range(0, clen, block_size):
+            chunk = ciphertext[i:i + block_size]
+            keystream = sha3(enc_key + prev).digest()[:len(chunk)]
+            plain_chunk = xor(chunk, keystream)
+            result.extend(plain_chunk)
+            prev = chunk
+        plain = bytes(result)
+        logger.debug("drvrs: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)
+
+    def lfsr(self, data, key, aad=None, layer=SecurityLayer.STANDARD,
+             output_raw=False, input_raw=False):
+        if input_raw:
+            data_bytes = data if isinstance(data, bytes) else data.encode('utf-8')
+        else:
+            self._validate_nonempty(data)
+            data_bytes = self._to_bytes(data)
+        self._validate_key(key, 'lfsr')
+        salt = self._secure_bytes(self._salt_size)
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        nonce = self._secure_bytes(16)
+        sha3 = hashlib.sha3_256
+        blake2b = hashlib.blake2b
+        stateA = sha3(enc_key + nonce).digest()
+        stateB = blake2b(enc_key + nonce, digest_size=32).digest()
+        result = bytearray()
+        for byte in data_bytes:
+            result.append(byte ^ (stateA[0] ^ stateB[0]))
+            stateA = sha3(stateA).digest()
+            stateB = blake2b(stateB, digest_size=32).digest()
+        ciphertext = bytes(result)
+        package = self._pack('lfsr', aad, salt, nonce, ciphertext, mac_key=mac_key)
+        logger.debug("lfsr: encrypted %d bytes", len(ciphertext))
+        return package if output_raw else base64.b85encode(package).decode('utf-8')
+
+    def dlfsr(self, encoded, key, aad=None, layer=SecurityLayer.STANDARD,
+              output_raw=False, input_raw=False):
+        if input_raw:
+            package = encoded if isinstance(encoded, bytes) else encoded.encode('utf-8')
+        else:
+            if not encoded:
+                raise ValueError("  Encoded data cannot be empty.")
+            package = encoded if isinstance(encoded, bytes) else base64.b85decode(encoded.encode('utf-8'))
+        self._validate_key(key, 'dlfsr')
+        aad_pkg, salt, nonce, ciphertext, mac_val = self._unpack(package, 'lfsr')
+        if aad is not None and aad != aad_pkg:
+            raise ValueError("  AAD mismatch")
+        enc_key, mac_key = self._derive_keys(key, salt, layer)
+        to_verify = package[:-len(mac_val)] if mac_val else package
+        if mac_val and not hmac.compare_digest(mac_val, self._mac(mac_key, to_verify)):
+            raise ValueError("  MAC verification failed")
+        sha3 = hashlib.sha3_256
+        blake2b = hashlib.blake2b
+        stateA = sha3(enc_key + nonce).digest()
+        stateB = blake2b(enc_key + nonce, digest_size=32).digest()
+        result = bytearray()
+        for byte in ciphertext:
+            result.append(byte ^ (stateA[0] ^ stateB[0]))
+            stateA = sha3(stateA).digest()
+            stateB = blake2b(stateB, digest_size=32).digest()
+        plain = bytes(result)
+        logger.debug("dlfsr: decrypted %d bytes", len(plain))
+        return plain if output_raw else self._to_str(plain)

jpassende/utils.py

@@ -0,0 +1,31 @@
+# Copyright 2026 J Code
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import secrets
+from typing import Union
+
+def to_bytes(data: Union[str, bytes]) -> bytes:
+    return data.encode('utf-8') if isinstance(data, str) else data
+
+def to_str(data: bytes) -> str:
+    return data.decode('utf-8') if isinstance(data, bytes) else data
+
+def secure_bytes(size: int = 32) -> bytes:
+    return secrets.token_bytes(size)
+
+def validate_nonempty(data: Union[str, bytes], name: str = "data"):
+    b = to_bytes(data)
+    if len(b) == 0:
+        raise ValueError(f"  Input {name} cannot be empty.")
+
+def validate_key(key: str, pattern: str = ""):
+    if not key:
+        raise ValueError(f"  Key must not be empty for pattern '{pattern}'.")
+
+def xor_bytes(a: bytes, b: bytes) -> bytes:
+    if len(a) != len(b):
+        raise ValueError(f"  Length mismatch in XOR: {len(a)} vs {len(b)}")
+    return bytes(x ^ y for x, y in zip(a, b))
+
+def mac(key: bytes, data: bytes) -> bytes:
+    return hashlib.blake2b(data, key=key, digest_size=32).digest()

jpassende-1.0.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: jpassende
+Version: 1.0.0
+Summary: High-Performance Cryptographic Library with Custom Patterns
+Author: J Code
+Project-URL: Homepage, https://github.com/JCode-JCode/jpassende
+Project-URL: Repository, https://github.com/JCode-JCode/jpassende
+Keywords: cryptography,encryption,security,aead,stream-cipher,block-cipher,key-derivation,high-performance
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: NOTICE
+Requires-Dist: pycryptodome>=3.18.0
+Dynamic: license-file
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI version](https://img.shields.io/pypi/v/jpassende)](https://pypi.org/project/jpassende/)
+[![PyPI project](https://img.shields.io/badge/PyPI-jpassende-blue)](https://pypi.org/project/jpassende/)
+
+<br>
+
+<img src="docs/images/jpassende-logo.png" alt="jpassende">
+
+<br>
+
+**jpassende** is a high‑performance, multi‑pattern cryptographic library for Python that goes far beyond standard encryption. It offers 14 unique patterns spanning AEAD, stream ciphers, block ciphers, and key derivation – all wrapped in a simple, consistent API. Every pattern uses its own distinct combination of algorithms and constructions, making your ciphertext immediately recognisable and self‑describing.
+
+---
+
+## Quick Start – Encrypt & Decrypt in Two Lines
+
+```python
+from jpassende import JPassende
+
+jp = JPassende()
+
+result = jp.encode("Hello, World!", "vail", key="my_secret")
+print(result.encoded)
+
+original = jp.decode(result.encoded, "vail", key="my_secret")
+print(original.decoded)
+```
+
+---
+
+## Main Capabilities
+
+**· AEAD Patterns** – vail (AES‑GCM), phnx (ChaCha20‑Poly1305), nixl (ChaCha20 + independent HMAC). All three provide authenticated encryption with associated data (AAD) support.
+
+**· Stream Patterns** – strx (BLAKE2‑based keystream), rvrs (SHA‑3 feedback mode), lfsr (dual‑state SHA‑3 / BLAKE2 generator). Byte‑by‑byte encryption without padding, ideal for streaming data.
+
+**· Block Patterns** – aegs (AES‑CTR + HMAC), cblk (AES‑CBC + HMAC), cfbb (AES‑CFB‑128 + HMAC), ofbb (AES‑OFB + HMAC). Standard block cipher modes, each individually authenticated.
+
+**· Derivation Patterns** – hkdf (HMAC‑based Extract‑and‑Expand), scrt (scrypt), pbk2 (PBKDF2‑SHA‑512), blk3 (Merkle‑tree commitment). Password hashing, key material generation, and data integrity commitments.
+
+**· Security Layers** – Every pattern supports three selectable security layers: STANDARD (300k PBKDF2 iterations), FORTIFIED (600k), and QUANTUM (1.2M). You control the trade‑off between speed and brute‑force resistance.
+
+**· Binary & Text I/O** – output_raw returns bytes instead of base‑encoded strings. input_raw accepts raw bytes directly, so you can encrypt binary files, images, or any byte sequence.
+
+**· Cross‑Instance Decryption** – Packages carry all the metadata (magic, version, pattern ID, salt, nonce) needed for decryption. Any JPassende instance anywhere can decrypt, provided it has the same key.
+
+**· Self‑Describing Packages** – The binary format includes a magic header, version byte, pattern identifier, and optional AAD. No more guessing which algorithm was used.
+
+**· LRU Key Cache** – PBKDF2 derivations are cached (thread‑safe LRU) to avoid redundant work when the same password is reused.
+
+**· Invalid Package Detection** – A dedicated InvalidPackageError is raised when the package structure, magic, or version is invalid.
+
+**· Zero Plaintext Password Storage** – Cache keys are derived from a BLAKE2b hash of (password + salt + parameters), never from the password itself.
+
+---
+
+## Pattern Status
+
+The patterns nixl, strx, rvrs, lfsr, aegs, cblk, cfbb, ofbb, hkdf, scrt, pbk2, and blk3 are custom constructions created exclusively for jpassende. They are currently experimental and under active development – their internal design may evolve as we gather feedback and perform further security analysis. The patterns vail (AES‑256‑GCM) and phnx (ChaCha20‑Poly1305) use standardized, well‑vetted algorithms and are considered stable. If you plan to use the experimental patterns in production, we strongly recommend performing your own security review and staying updated with new releases.
+
+---
+
+## Installation
+
+```bash
+pip install jpassende
+```
+
+jpassende depends only on pycryptodome (≥ 3.18) and Python's standard library.
+
+---
+
+## More Examples
+
+Encrypting Binary Data (input_raw / output_raw)
+
+```python
+from jpassende import JPassende
+
+jp = JPassende()
+image = open("photo.png", "rb").read()
+
+enc_pkg = jp.encode(image, "nixl", key="secret", input_raw=True, output_raw=True)
+
+dec_bytes = jp.decode(enc_pkg.encoded, "nixl", key="secret",
+                      input_raw=True, output_raw=True).decoded
+
+with open("photo_decrypted.png", "wb") as f:
+    f.write(dec_bytes)
+```
+
+## Choosing a Security Layer
+
+```python
+from jpassende import JPassende, SecurityLayer
+
+jp = JPassende()
+
+result = jp.encode("Sensitive data", "phnx", key="strong",
+                   layer=SecurityLayer.QUANTUM)
+print(result.layer)
+```
+
+## Using AAD (Additional Authenticated Data)
+
+```python
+aad = b"user-id:12345"
+result = jp.encode("Hello", "vail", key="secret", aad=aad)
+decoded = jp.decode(result.encoded, "vail", key="secret", aad=aad)
+```
+
+## Key Derivation – HKDF
+
+```python
+derived = jp.encode("master-seed", "hkdf", key="secret", length=32)
+print(derived.encoded[:30] + "...")
+
+verified = jp.decode(derived.encoded, "hkdf", key="secret")
+print(verified.decoded[:20] + "...")
+```
+
+## List All Available Patterns
+
+```python
+from jpassende import JPassende
+
+print(JPassende.PATTERNS.keys())
+```
+
+---
+
+## Error Handling
+
+```python
+from jpassende import JPassende, InvalidPackageError
+
+jp = JPassende()
+
+try:
+    jp.decode("not-valid-data", "vail", key="secret")
+except InvalidPackageError as e:
+    print(f"Package error: {e}")
+except ValueError as e:
+    print(f"Other error: {e}")
+```
+
+---
+
+## Issues and Contributions
+
+Bug reports and feature requests are welcome via GitHub Issues. Pull requests should maintain the existing code style and include tests where appropriate.
+
+---
+
+## Links
+
+**· GitHub repository:**
+https://github.com/JCode-JCode/jpassende
+
+**· PyPI page:**
+https://pypi.org/project/jpassende/
+
+---
+
+## License
+
+This project is licensed under the Apache License 2.0 – see the LICENSE file for details.
+
+---
+
+Designed and built with love by **J Code**

jpassende-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+jpassende/__init__.py,sha256=4BNG9xq3Xwj74UysbbEMCxkQoDTsnBI-fMeOwHObMEE,429
+jpassende/_version.py,sha256=auvrWpJXBBfRo-mNTNbK4eb88E9f5nUxM4PK02c429M,83
+jpassende/core.py,sha256=UuOUqib1fEAL--h9r9u5_nH3IbWAo1xdqCxFwOrFhQ8,11892
+jpassende/datatypes.py,sha256=MqAgfZA_dutVIkTz1yqSVSa9ceZgTssMX4o54pPHS_4,474
+jpassende/enums.py,sha256=krBut1SLq_b_zEkp2v0TBIcdDdHEN5Hsl6X3wyJnQq4,294
+jpassende/exceptions.py,sha256=NOFfcP-uLlzDMoXzdNrFPgITsetAUUVAAxbzrSx8TSI,109
+jpassende/utils.py,sha256=xvPgjm2dF-z_jraGaBm9AKA9gxRlurRyO9oLiKiDJiY,1033
+jpassende/mixins/__init__.py,sha256=8gJomFQIP8dO-2cEV5sw3yCkDGO3U_eRjVw-AWCrsLo,107
+jpassende/mixins/aead.py,sha256=LyBsAVt2rJ603-25XbsYvG8z_47_L08TaQAi0c-RnQc,6912
+jpassende/mixins/block.py,sha256=8r2mHV_2m8CHeUF7xGJ9WIHoEGf4Jnp3imoaMCuZhR4,8846
+jpassende/mixins/derivation.py,sha256=QnLjR5OvMW8wmFOc4e6zz4X9vcLG7Oeup62hL9FAobM,9084
+jpassende/mixins/stream.py,sha256=Hi2k12OSntKS8petUYjP-_Sy-VkY06Ywok9no24F3cg,8729
+jpassende-1.0.0.dist-info/licenses/NOTICE,sha256=0cAPLxMWRM0zFHFjSGF2AO5_jMdmnkb-b-CHwo41pPY,59
+jpassende-1.0.0.dist-info/METADATA,sha256=erd8mcxUfLDwnzYcmKsObenRMqxQRs656SnPyCbI1xo,7231
+jpassende-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+jpassende-1.0.0.dist-info/top_level.txt,sha256=PHB9hNDtDWUPPBPBoqlpPTR3vjgluv3ImNpW-07gGuA,10
+jpassende-1.0.0.dist-info/RECORD,,

jpassende-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jpassende-1.0.0.dist-info/licenses/NOTICE

@@ -0,0 +1,2 @@
+jpassende
+Copyright 2026 J Code(Mohammadjavad Maleki Kaveh)

jpassende-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jpassende