filanti 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

filanti/crypto/encryption.py

@@ -9,6 +9,7 @@ Supported algorithms:
 - ChaCha20-Poly1305 (excellent software performance)
 """
 
+import base64
 import json
 from dataclasses import dataclass, asdict
 from enum import Enum
@@ -37,7 +38,12 @@ DEFAULT_ALGORITHM = EncryptionAlgorithm.AES_256_GCM
 
 # File format magic bytes
 FILANTI_MAGIC = b"FLNT"
-FORMAT_VERSION = 1
+FORMAT_VERSION = 1  # Legacy v1 format version
+FORMAT_VERSION_V2 = 2  # New v2 format with encrypted metadata
+
+# Product identifier for header
+PRODUCT_NAME = "FLNT"
+HEADER_VERSION = "1.1.0"
 
 # Chunk size for streaming encryption (64 KB)
 CHUNK_SIZE = 65536
@@ -151,6 +157,37 @@ class EncryptionMetadata:
         return cls(**parsed)
 
 
+@dataclass
+class FileHeader:
+    """Minimal public header for encrypted files - base64 encoded.
+
+    Only exposes product name and version, no cryptographic details.
+    """
+
+    product: str = PRODUCT_NAME
+    version: str = HEADER_VERSION
+
+    def to_base64(self) -> bytes:
+        """Encode header as base64 bytes."""
+        data = {"p": self.product, "v": self.version}
+        json_bytes = json.dumps(data, separators=(",", ":")).encode("utf-8")
+        return base64.b64encode(json_bytes)
+
+    @classmethod
+    def from_base64(cls, data: bytes) -> "FileHeader":
+        """Decode header from base64 bytes."""
+        try:
+            json_bytes = base64.b64decode(data)
+            parsed = json.loads(json_bytes.decode("utf-8"))
+            return cls(product=parsed.get("p", "FLNT"), version=parsed.get("v", "1.0.0"))
+        except Exception as e:
+            raise EncryptionError(f"Invalid file header: {e}") from e
+
+    def validate(self) -> bool:
+        """Validate the header is from Filanti."""
+        return self.product == PRODUCT_NAME
+
+
 def _get_cipher(algorithm: EncryptionAlgorithm, key: bytes):
     """Get the appropriate cipher for the algorithm."""
     if algorithm == EncryptionAlgorithm.AES_256_GCM:
@@ -270,6 +307,8 @@ def encrypt_file(
     key: bytes,
     algorithm: EncryptionAlgorithm = DEFAULT_ALGORITHM,
     file_manager: FileManager | None = None,
+    remove_source: bool = False,
+    secure_delete: bool = True,
 ) -> EncryptionMetadata:
     """Encrypt a file using authenticated encryption.
 
@@ -279,6 +318,9 @@ def encrypt_file(
         key: Encryption key.
         algorithm: Encryption algorithm to use.
         file_manager: Optional FileManager instance.
+        remove_source: If True, delete original file after successful encryption.
+        secure_delete: If True and remove_source is True, securely overwrite
+            the original file before deletion (defense in depth).
 
     Returns:
         EncryptionMetadata for the encrypted file.
@@ -309,6 +351,13 @@ def encrypt_file(
         output = _build_encrypted_file(result.ciphertext, metadata)
         fm.write_bytes(output_path, output)
 
+        # Remove source file if requested
+        if remove_source:
+            if secure_delete:
+                fm.secure_delete(input_path)
+            else:
+                fm.delete(input_path)
+
         return metadata
 
     except (EncryptionError, FileOperationError):
@@ -328,6 +377,8 @@ def encrypt_file_with_password(
     algorithm: EncryptionAlgorithm = DEFAULT_ALGORITHM,
     kdf_params: KDFParams | None = None,
     file_manager: FileManager | None = None,
+    remove_source: bool = False,
+    secure_delete: bool = True,
 ) -> EncryptionMetadata:
     """Encrypt a file using a password.
 
@@ -338,6 +389,9 @@ def encrypt_file_with_password(
         algorithm: Encryption algorithm to use.
         kdf_params: Optional KDF parameters.
         file_manager: Optional FileManager instance.
+        remove_source: If True, delete original file after successful encryption.
+        secure_delete: If True and remove_source is True, securely overwrite
+            the original file before deletion (defense in depth).
 
     Returns:
         EncryptionMetadata for the encrypted file.
@@ -373,6 +427,13 @@ def encrypt_file_with_password(
         output = _build_encrypted_file(result.ciphertext, metadata)
         fm.write_bytes(output_path, output)
 
+        # Remove source file if requested
+        if remove_source:
+            if secure_delete:
+                fm.secure_delete(input_path)
+            else:
+                fm.delete(input_path)
+
         return metadata
 
     except (EncryptionError, FileOperationError):
@@ -386,12 +447,56 @@ def encrypt_file_with_password(
 
 
 def _build_encrypted_file(ciphertext: bytes, metadata: EncryptionMetadata) -> bytes:
-    """Build encrypted file with header.
+    """Build encrypted file with v2 format (encrypted metadata).
+
+    File format v2:
+    - N bytes: Base64 header ({"p":"FLNT","v":"1.1.0"})
+    - 2 bytes: Header length (big-endian uint16)
+    - 12 bytes: Metadata nonce (for deriving metadata key and encryption)
+    - 4 bytes: Encrypted metadata length (big-endian uint32)
+    - M bytes: Encrypted metadata ciphertext
+    - K bytes: File ciphertext
+
+    The metadata is encrypted using AES-GCM with a key derived from:
+    SHA-256(metadata_nonce || "filanti-meta-v2")
+    """
+    from hashlib import sha256
+
+    # Create minimal public header
+    header = FileHeader()
+    header_b64 = header.to_base64()
+
+    # Generate a random nonce for metadata encryption
+    meta_nonce = generate_nonce(NONCE_SIZE_GCM)
+
+    # Derive metadata encryption key from the nonce
+    meta_key = sha256(meta_nonce + b"filanti-meta-v2").digest()
+
+    # Encrypt metadata using AES-GCM
+    meta_plaintext = metadata.to_bytes()
+    meta_cipher = AESGCM(meta_key)
+    meta_ciphertext = meta_cipher.encrypt(meta_nonce, meta_plaintext, None)
 
-    File format:
+    # Assemble v2 file
+    parts = [
+        header_b64,                                    # Base64 header
+        len(header_b64).to_bytes(2, "big"),           # Header length (2 bytes)
+        meta_nonce,                                    # Metadata nonce (12 bytes)
+        len(meta_ciphertext).to_bytes(4, "big"),      # Encrypted metadata length (4 bytes)
+        meta_ciphertext,                               # Encrypted metadata
+        ciphertext,                                    # File ciphertext
+    ]
+
+    return b"".join(parts)
+
+
+def _build_encrypted_file_v1(ciphertext: bytes, metadata: EncryptionMetadata) -> bytes:
+    """Build encrypted file with legacy v1 format (plaintext metadata).
+
+    File format v1 (legacy):
     - 4 bytes: Magic ("FLNT")
     - 4 bytes: Metadata length (big-endian uint32)
-    - N bytes: Metadata (JSON)
+    - N bytes: Metadata (JSON plaintext)
     - M bytes: Ciphertext
     """
     meta_bytes = metadata.to_bytes()
@@ -403,6 +508,8 @@ def _build_encrypted_file(ciphertext: bytes, metadata: EncryptionMetadata) -> by
 def parse_encrypted_file(data: bytes) -> tuple[EncryptionMetadata, bytes]:
     """Parse encrypted file header and extract ciphertext.
 
+    Supports both v1 (legacy) and v2 formats.
+
     Args:
         data: Encrypted file bytes.
 
@@ -415,6 +522,16 @@ def parse_encrypted_file(data: bytes) -> tuple[EncryptionMetadata, bytes]:
     if len(data) < 8:
         raise EncryptionError("Invalid encrypted file: too short")
 
+    # Check for v1 format (starts with raw FLNT magic bytes)
+    if data[:4] == FILANTI_MAGIC:
+        return _parse_encrypted_file_v1(data)
+
+    # Try v2 format (starts with base64-encoded header)
+    return _parse_encrypted_file_v2(data)
+
+
+def _parse_encrypted_file_v1(data: bytes) -> tuple[EncryptionMetadata, bytes]:
+    """Parse legacy v1 format encrypted file."""
     if data[:4] != FILANTI_MAGIC:
         raise EncryptionError("Invalid encrypted file: bad magic bytes")
 
@@ -433,3 +550,92 @@ def parse_encrypted_file(data: bytes) -> tuple[EncryptionMetadata, bytes]:
 
     return metadata, ciphertext
 
+
+def _parse_encrypted_file_v2(data: bytes) -> tuple[EncryptionMetadata, bytes]:
+    """Parse v2 format encrypted file with encrypted metadata.
+
+    File format v2:
+    - N bytes: Base64 header
+    - 2 bytes: Header length
+    - 12 bytes: Metadata nonce
+    - 4 bytes: Encrypted metadata length
+    - M bytes: Encrypted metadata
+    - K bytes: File ciphertext
+    """
+    from hashlib import sha256
+
+    try:
+        # Find header boundary by scanning for valid base64 header
+        header_b64 = None
+        header_len_pos = None
+
+        for try_len in range(20, 64):
+            if try_len + 2 > len(data):
+                break
+            potential_header = data[:try_len]
+            potential_len = int.from_bytes(data[try_len:try_len+2], "big")
+            if potential_len == try_len:
+                # Found matching header length
+                try:
+                    FileHeader.from_base64(potential_header)
+                    header_b64 = potential_header
+                    header_len_pos = try_len
+                    break
+                except Exception:
+                    continue
+
+        if header_b64 is None:
+            raise EncryptionError("Invalid encrypted file: cannot parse v2 header")
+
+        # Parse and validate header
+        header = FileHeader.from_base64(header_b64)
+        if not header.validate():
+            raise EncryptionError("Invalid encrypted file: wrong product identifier")
+
+        offset = header_len_pos + 2  # Skip header + header length bytes
+
+        # Read metadata nonce (12 bytes)
+        if len(data) < offset + NONCE_SIZE_GCM:
+            raise EncryptionError("Invalid encrypted file: truncated")
+
+        meta_nonce = data[offset:offset + NONCE_SIZE_GCM]
+        offset += NONCE_SIZE_GCM
+
+        # Read encrypted metadata length
+        if len(data) < offset + 4:
+            raise EncryptionError("Invalid encrypted file: truncated")
+
+        encrypted_meta_len = int.from_bytes(data[offset:offset+4], "big")
+        offset += 4
+
+        # Read encrypted metadata
+        if len(data) < offset + encrypted_meta_len:
+            raise EncryptionError("Invalid encrypted file: truncated metadata")
+
+        meta_ciphertext = data[offset:offset + encrypted_meta_len]
+        offset += encrypted_meta_len
+
+        # Extract file ciphertext
+        ciphertext = data[offset:]
+
+        # Derive metadata decryption key
+        meta_key = sha256(meta_nonce + b"filanti-meta-v2").digest()
+
+        # Decrypt metadata
+        meta_cipher = AESGCM(meta_key)
+        try:
+            meta_plaintext = meta_cipher.decrypt(meta_nonce, meta_ciphertext, None)
+        except InvalidTag:
+            raise EncryptionError("Invalid encrypted file: metadata authentication failed")
+
+        # Parse metadata
+        metadata = EncryptionMetadata.from_bytes(meta_plaintext)
+
+        return metadata, ciphertext
+
+    except EncryptionError:
+        raise
+    except Exception as e:
+        raise EncryptionError(f"Invalid encrypted file format: {e}") from e
+
+

filanti/integrity/mac.py

@@ -99,16 +99,69 @@ class IntegrityMetadata:
         """Serialize to JSON string."""
         return json.dumps(asdict(self), indent=indent, sort_keys=True)
 
+    def to_json_minimal(self) -> str:
+        """Serialize to minimal JSON (reduced information leakage)."""
+        # Only include essential fields: version, mac, algorithm
+        # Omit: filename, filesize, created_at
+        minimal = {
+            "v": "2",  # Minimal format version
+            "m": self.mac,
+            "a": self._short_algorithm(self.algorithm) if self.algorithm else None,
+        }
+        return json.dumps(minimal, separators=(",", ":"))
+
+    @staticmethod
+    def _short_algorithm(algorithm: str) -> str:
+        """Convert algorithm to short form."""
+        short_map = {
+            "hmac-sha256": "hs256",
+            "hmac-sha384": "hs384",
+            "hmac-sha512": "hs512",
+            "hmac-sha3-256": "hs3256",
+            "hmac-blake2b": "hb2b",
+        }
+        return short_map.get(algorithm, algorithm)
+
+    @staticmethod
+    def _expand_algorithm(short: str) -> str:
+        """Convert short algorithm to full form."""
+        expand_map = {
+            "hs256": "hmac-sha256",
+            "hs384": "hmac-sha384",
+            "hs512": "hmac-sha512",
+            "hs3256": "hmac-sha3-256",
+            "hb2b": "hmac-blake2b",
+        }
+        return expand_map.get(short, short)
+
     @classmethod
     def from_json(cls, json_str: str) -> "IntegrityMetadata":
-        """Deserialize from JSON string."""
+        """Deserialize from JSON string (supports v1 and v2/minimal formats)."""
         data = json.loads(json_str)
+
+        # Check for minimal v2 format
+        if "v" in data and data.get("v") == "2":
+            return cls(
+                version="2.0",
+                mac=data.get("m"),
+                algorithm=cls._expand_algorithm(data.get("a", "")),
+            )
+
+        # Standard v1 format
         return cls(**data)
 
-    def save(self, path: str | Path) -> None:
-        """Save metadata to file."""
+    def save(self, path: str | Path, minimal: bool = False) -> None:
+        """Save metadata to file.
+
+        Args:
+            path: Output path.
+            minimal: If True, use minimal format (reduced information leakage).
+        """
         path = Path(path)
-        path.write_text(self.to_json(), encoding="utf-8")
+        if minimal:
+            path.write_text(self.to_json_minimal(), encoding="utf-8")
+        else:
+            path.write_text(self.to_json(), encoding="utf-8")
 
     @classmethod
     def load(cls, path: str | Path) -> "IntegrityMetadata":
@@ -384,6 +437,7 @@ def create_integrity_file(
     key: bytes,
     algorithm: MACAlgorithm | str = DEFAULT_ALGORITHM,
     output_path: str | Path | None = None,
+    minimal: bool = False,
 ) -> Path:
     """Create detached integrity metadata file.
 
@@ -392,6 +446,8 @@ def create_integrity_file(
         key: Secret key for HMAC.
         algorithm: MAC algorithm to use.
         output_path: Optional output path (default: file_path + '.mac')
+        minimal: If True, use minimal format (reduced information leakage).
+            Only includes version, MAC, and algorithm (no filename, filesize, timestamp).
 
     Returns:
         Path to the created integrity file.
@@ -408,13 +464,13 @@ def create_integrity_file(
     metadata = IntegrityMetadata(
         mac=result.to_hex(),
         algorithm=result.algorithm,
-        filename=file_path.name,
-        filesize=file_path.stat().st_size,
-        created_at=result.created_at,
+        filename=file_path.name if not minimal else None,
+        filesize=file_path.stat().st_size if not minimal else None,
+        created_at=result.created_at if not minimal else None,
     )
 
     try:
-        metadata.save(output_path)
+        metadata.save(output_path, minimal=minimal)
         return output_path
     except Exception as e:
         raise FileOperationError(

{filanti-1.0.0.dist-info → filanti-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: filanti
-Version: 1.0.0
+Version: 1.1.0
 Summary: A modular, security-focused file framework for encryption, hashing, and integrity verification
 License: MIT
 License-File: LICENSE
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-**Filanti** is a production-ready Python framework providing secure-by-default primitives for:
+**Filanti** is a Python framework providing secure-by-default primitives for:
 
 -  **File Encryption** - AES-256-GCM, ChaCha20-Poly1305 with password-based encryption
 -  **Asymmetric Encryption** - Hybrid encryption with X25519, RSA-OAEP for multi-recipient file exchange
@@ -359,6 +359,15 @@ with SecureString("my-password") as pwd:
 
 Secure secret injection for automation and CI/CD workflows. Avoid hardcoding passwords in scripts or command lines.
 
+**Supported Patterns:**
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `ENV:VAR` | Unix-style (original) | `ENV:MY_PASSWORD` |
+| `$env:VAR` | PowerShell-style | `$env:MY_PASSWORD` |
+| `${VAR}` | Shell variable expansion | `${MY_PASSWORD}` |
+| `env.VAR` | Dot notation (cross-platform) | `env.MY_PASSWORD` |
+
 ```python
 import os
 from filanti.api import Filanti
@@ -366,12 +375,23 @@ from filanti.api import Filanti
 # Set secret in environment (done by CI/CD, Docker, etc.)
 os.environ["ENCRYPT_PASSWORD"] = "my-secure-password"
 
-# Use ENV reference - secret is resolved at runtime
-Filanti.encrypt("secret.txt", password="ENV:ENCRYPT_PASSWORD")
-Filanti.decrypt("secret.txt.enc", password="ENV:ENCRYPT_PASSWORD")
+# All patterns are supported
+Filanti.encrypt("secret.txt", password="ENV:ENCRYPT_PASSWORD")      # Unix-style
+Filanti.encrypt("secret.txt", password="$env:ENCRYPT_PASSWORD")     # PowerShell
+Filanti.encrypt("secret.txt", password="${ENCRYPT_PASSWORD}")       # Shell-style
+Filanti.encrypt("secret.txt", password="env.ENCRYPT_PASSWORD")      # Dot notation
+
+# Load secrets from .env file
+Filanti.load_dotenv(".env")
+Filanti.encrypt("secret.txt", password="ENV:SECRET_FROM_DOTENV")
+
+# Or load during encryption
+Filanti.encrypt("secret.txt", password="ENV:MY_KEY", dotenv_path=".env")
 
 # Check if value is an ENV reference
-Filanti.is_env_reference("ENV:MY_SECRET")  # True
+Filanti.is_env_reference("ENV:MY_SECRET")     # True
+Filanti.is_env_reference("$env:MY_SECRET")    # True
+Filanti.is_env_reference("${MY_SECRET}")      # True
 
 # Resolve secret manually
 password = Filanti.resolve_secret("ENV:ENCRYPT_PASSWORD")
@@ -392,11 +412,25 @@ safe = Filanti.safe_json_output(data, secret_keys=["password"])
 # Set environment variable
 export ENCRYPT_PASSWORD="my-secure-password"
 
-# Use in CLI commands
+# All pattern formats work in --password
 filanti encrypt secret.txt --password ENV:ENCRYPT_PASSWORD
-filanti decrypt secret.txt.enc --password ENV:ENCRYPT_PASSWORD
-filanti mac file.txt --key ENV:HMAC_KEY
-filanti sign document.pdf --key mykey --password ENV:KEY_PASSWORD
+filanti encrypt secret.txt --password '$env:ENCRYPT_PASSWORD'  # PowerShell
+filanti encrypt secret.txt --password '${ENCRYPT_PASSWORD}'    # Shell-style
+filanti encrypt secret.txt --password env.ENCRYPT_PASSWORD     # Dot notation
+
+# PowerShell-friendly --env option (no special characters)
+filanti encrypt secret.txt --env ENCRYPT_PASSWORD
+filanti decrypt secret.txt.enc --env ENCRYPT_PASSWORD
+
+# Load from .env file
+filanti encrypt secret.txt --dotenv .env --env-key MY_PASSWORD
+filanti mac file.txt --dotenv secrets.env --env-key HMAC_KEY
+
+# All secret-accepting commands support these options:
+#   --password   Literal or ENV pattern
+#   --env        Variable name (PowerShell-friendly)
+#   --dotenv     Path to .env file
+#   --env-key    Variable name from .env file
 ```
 
 **Benefits:**
@@ -404,6 +438,43 @@ filanti sign document.pdf --key mykey --password ENV:KEY_PASSWORD
 -  Works with CI/CD (GitHub Actions, GitLab CI, Jenkins)
 -  Compatible with Docker/Kubernetes secrets
 -  12-factor app compliance
+-  PowerShell-native syntax support
+-  Cross-platform .env file loading
+
+###  Secure File Deletion
+
+Delete original files securely after encryption/decryption operations.
+
+```python
+from filanti.api import Filanti
+
+# Encrypt and securely delete original
+Filanti.encrypt("secret.txt", password="my-pass", remove_source=True)
+# Original file is securely overwritten before deletion
+
+# Decrypt and remove encrypted file
+Filanti.decrypt("secret.txt.enc", password="my-pass", remove_source=True)
+# Encrypted file is securely deleted after decryption
+
+# Use faster (non-secure) deletion
+Filanti.encrypt("secret.txt", password="my-pass", 
+                remove_source=True, secure_delete=False)
+```
+
+**CLI Support:**
+
+```bash
+# Encrypt and securely delete original
+filanti encrypt secret.txt --password mypass --remove-source
+
+# Decrypt and remove encrypted file
+filanti decrypt secret.txt.enc --password mypass --remove-source
+
+# Use faster (non-secure) deletion
+filanti encrypt secret.txt --password mypass --remove-source --no-secure-delete
+```
+
+> ⚠️ **Note:** Secure deletion provides defense-in-depth but has limitations on SSDs with wear-leveling, journaling filesystems, and cloud-synced folders. For maximum security, use full-disk encryption.
 
 ###  Asymmetric / Hybrid Encryption
 
@@ -834,40 +905,72 @@ safe_output = redact_secret("Password is secret123", "secret123")
 
 ---
 
-## Architecture
+[//]: # (## Architecture)
 
-```
-filanti/
-├── core/              
-│   ├── errors.py      
-│   ├── file_manager.py 
-│   ├── metadata.py    
-│   ├── plugins.py     
-│   ├── secrets.py     
-│   └── secure_memory.py 
-│
-├── crypto/            
-│   ├── encryption.py  
-│   ├── decryption.py  
-│   ├── key_management.py 
-│   ├── kdf.py         
-│   ├── streaming.py   
-│   └── asymmetric.py  
-│
-├── hashing/           
-│   └── crypto_hash.py 
-│
-├── integrity/        
-│   ├── checksum.py    
-│   ├── mac.py         
-│   └── signature.py   
-│
-├── cli/               
-│   └── main.py        
-│
-└── api/               
-    └── sdk.py         
-```
+[//]: # ()
+[//]: # (```)
+
+[//]: # (filanti/)
+
+[//]: # (├── core/              )
+
+[//]: # (│   ├── errors.py      )
+
+[//]: # (│   ├── file_manager.py )
+
+[//]: # (│   ├── metadata.py    )
+
+[//]: # (│   ├── plugins.py     )
+
+[//]: # (│   ├── secrets.py     )
+
+[//]: # (│   └── secure_memory.py )
+
+[//]: # (│)
+
+[//]: # (├── crypto/            )
+
+[//]: # (│   ├── encryption.py  )
+
+[//]: # (│   ├── decryption.py  )
+
+[//]: # (│   ├── key_management.py )
+
+[//]: # (│   ├── kdf.py         )
+
+[//]: # (│   ├── streaming.py   )
+
+[//]: # (│   └── asymmetric.py  )
+
+[//]: # (│)
+
+[//]: # (├── hashing/           )
+
+[//]: # (│   └── crypto_hash.py )
+
+[//]: # (│)
+
+[//]: # (├── integrity/        )
+
+[//]: # (│   ├── checksum.py    )
+
+[//]: # (│   ├── mac.py         )
+
+[//]: # (│   └── signature.py   )
+
+[//]: # (│)
+
+[//]: # (├── cli/               )
+
+[//]: # (│   └── main.py        )
+
+[//]: # (│)
+
+[//]: # (└── api/               )
+
+[//]: # (    └── sdk.py         )
+
+[//]: # (```)
 
 ### Module Dependencies
 
@@ -1128,7 +1231,8 @@ encrypt_stream_file(input_path, output_path, key, chunk_size=16*1024)   # 16 KB
 
 ---
 
-## Contributing
+## Contributors || Acknowledgements
+[@stephenlb](https://github.com/stephenlb) Thanks for the inspiration and guidance on encryption and security best practices.
 
 ### Development Setup
 
@@ -1159,15 +1263,21 @@ pip install -e ".[dev]"
 
 [//]: # (```)
 
-### Pull Request Guidelines
+[//]: # (### Pull Request Guidelines)
 
-1. Write tests for new features
-2. Update documentation
-3. Follow existing code style
-4. Add type hints
-5. Run full test suite before submitting
+[//]: # ()
+[//]: # (1. Write tests for new features)
 
----
+[//]: # (2. Update documentation)
+
+[//]: # (3. Follow existing code style)
+
+[//]: # (4. Add type hints)
+
+[//]: # (5. Run full test suite before submitting)
+
+[//]: # ()
+[//]: # (---)
 
 ## Changelog