jpassende 1.0.0__tar.gz

jpassende-1.0.0/NOTICE

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

jpassende-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,173 @@
+[![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/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-1.0.0/jpassende/_version.py

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

jpassende-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())