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

filanti/__init__.py

@@ -5,7 +5,7 @@ Provides secure-by-default primitives for file encryption, hashing,
 and integrity verification.
 """
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __author__ = "Decliqe"
 
 from filanti.core.errors import (

filanti/api/sdk.py

@@ -145,6 +145,9 @@ from filanti.core.secrets import (
     resolve_secret,
     resolve_secret_optional,
     is_env_reference,
+    get_env_var_name,
+    load_dotenv,
+    get_supported_patterns,
     redact_secret,
     redact_secrets,
     create_safe_json_output,
@@ -215,6 +218,36 @@ class Filanti:
     use the underlying modules directly.
     """
 
+    # =========================================================================
+    # SECRETS & ENVIRONMENT
+    # =========================================================================
+
+    @staticmethod
+    def load_dotenv(
+        path: str | Path = ".env",
+        override: bool = False,
+    ) -> dict[str, str]:
+        """Load environment variables from a .env file.
+
+        Loads variables from the specified .env file into the environment.
+        This is useful for loading secrets before encryption/decryption.
+
+        Args:
+            path: Path to .env file (default: ".env" in current directory).
+            override: If True, override existing environment variables.
+
+        Returns:
+            Dictionary of loaded variables (name -> value).
+
+        Example:
+            # Load secrets from .env
+            Filanti.load_dotenv(".env")
+
+            # Now use ENV references
+            Filanti.encrypt("file.txt", password="ENV:MY_PASSWORD")
+        """
+        return load_dotenv(path, override=override)
+
     # =========================================================================
     # HASHING
     # =========================================================================
@@ -308,20 +341,30 @@ class Filanti:
         key: bytes | None = None,
         output: str | Path | None = None,
         algorithm: str = "aes-256-gcm",
+        remove_source: bool = False,
+        secure_delete: bool = True,
+        dotenv_path: str | Path | None = None,
     ) -> EncryptResult:
         """Encrypt a file.
 
         Provide either password OR key, not both.
 
-        Supports ENV-based secret resolution for password:
+        Supports multiple secret reference formats:
             Filanti.encrypt("file.txt", password="ENV:MY_PASSWORD")
+            Filanti.encrypt("file.txt", password="$env:MY_PASSWORD")  # PowerShell
+            Filanti.encrypt("file.txt", password="${MY_PASSWORD}")    # Shell-style
+            Filanti.encrypt("file.txt", password="env.MY_PASSWORD")   # Dot notation
 
         Args:
             path: Path to file to encrypt.
-            password: Password for key derivation. Supports ENV:VAR_NAME syntax.
+            password: Password for key derivation. Supports ENV reference syntax.
             key: Raw encryption key (32 bytes for AES-256).
             output: Output path (default: path + .enc).
             algorithm: Encryption algorithm.
+            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.
+            dotenv_path: Optional path to .env file to load secrets from.
 
         Returns:
             EncryptResult with output path and metadata.
@@ -335,15 +378,23 @@ class Filanti:
 
         if password:
             # Resolve password from ENV if needed
-            resolved_password = resolve_secret(password)
-            metadata = encrypt_file_with_password(path, out_path, resolved_password, alg)
+            resolved_password = resolve_secret(password, dotenv_path=dotenv_path)
+            metadata = encrypt_file_with_password(
+                path, out_path, resolved_password, alg,
+                remove_source=remove_source,
+                secure_delete=secure_delete,
+            )
             return EncryptResult(
                 output_path=out_path,
                 algorithm=metadata.algorithm,
                 kdf_algorithm=metadata.kdf_algorithm,
             )
         elif key:
-            encrypt_file(path, out_path, key, alg)
+            encrypt_file(
+                path, out_path, key, alg,
+                remove_source=remove_source,
+                secure_delete=secure_delete,
+            )
             return EncryptResult(output_path=out_path, algorithm=algorithm)
         else:
             raise ValueError("Must provide either password or key")
@@ -354,19 +405,29 @@ class Filanti:
         password: str | None = None,
         key: bytes | None = None,
         output: str | Path | None = None,
+        dotenv_path: str | Path | None = None,
+        remove_source: bool = False,
+        secure_delete: bool = True,
     ) -> DecryptResult:
         """Decrypt a file.
 
         Provide either password OR key, not both.
 
-        Supports ENV-based secret resolution for password:
+        Supports multiple secret reference formats:
             Filanti.decrypt("file.enc", password="ENV:MY_PASSWORD")
+            Filanti.decrypt("file.enc", password="$env:MY_PASSWORD")  # PowerShell
+            Filanti.decrypt("file.enc", password="${MY_PASSWORD}")    # Shell-style
+            Filanti.decrypt("file.enc", password="env.MY_PASSWORD")   # Dot notation
 
         Args:
             path: Path to encrypted file.
-            password: Password used for encryption. Supports ENV:VAR_NAME syntax.
+            password: Password used for encryption. Supports ENV reference syntax.
             key: Raw encryption key.
             output: Output path (default: removes .enc extension).
+            dotenv_path: Optional path to .env file to load secrets from.
+            remove_source: If True, delete encrypted file after successful decryption.
+            secure_delete: If True and remove_source is True, securely overwrite
+                the encrypted file before deletion.
 
         Returns:
             DecryptResult with output path and size.
@@ -384,13 +445,22 @@ class Filanti:
 
         if password:
             # Resolve password from ENV if needed
-            resolved_password = resolve_secret(password)
+            resolved_password = resolve_secret(password, dotenv_path=dotenv_path)
             size = decrypt_file_with_password(path, out_path, resolved_password)
         elif key:
             size = decrypt_file(path, out_path, key)
         else:
             raise ValueError("Must provide either password or key")
 
+        # Remove encrypted source file if requested
+        if remove_source:
+            from filanti.core.file_manager import get_file_manager
+            fm = get_file_manager()
+            if secure_delete:
+                fm.secure_delete(path)
+            else:
+                fm.delete(path)
+
         return DecryptResult(output_path=out_path, size=size)
 
     @staticmethod
@@ -399,17 +469,22 @@ class Filanti:
         password: str | None = None,
         key: bytes | None = None,
         algorithm: str = "aes-256-gcm",
+        dotenv_path: str | Path | None = None,
     ) -> bytes:
         """Encrypt bytes data.
 
-        Supports ENV-based secret resolution for password:
+        Supports multiple secret reference formats:
             Filanti.encrypt_bytes(data, password="ENV:MY_PASSWORD")
+            Filanti.encrypt_bytes(data, password="$env:MY_PASSWORD")  # PowerShell
+            Filanti.encrypt_bytes(data, password="${MY_PASSWORD}")    # Shell-style
+            Filanti.encrypt_bytes(data, password="env.MY_PASSWORD")   # Dot notation
 
         Args:
             data: Data to encrypt.
-            password: Password for key derivation. Supports ENV:VAR_NAME syntax.
+            password: Password for key derivation. Supports ENV reference syntax.
             key: Raw encryption key.
             algorithm: Encryption algorithm.
+            dotenv_path: Optional path to .env file to load secrets from.
 
         Returns:
             Encrypted bytes (includes nonce and auth tag).
@@ -421,7 +496,7 @@ class Filanti:
 
         if password is not None:
             # Resolve password from ENV if needed
-            resolved_password = resolve_secret(password)
+            resolved_password = resolve_secret(password, dotenv_path=dotenv_path)
             result = _encrypt_bytes_with_password(data, resolved_password, alg)
             return result.to_bytes()
         elif key is not None:
@@ -436,16 +511,21 @@ class Filanti:
         data: bytes,
         password: str | None = None,
         key: bytes | None = None,
+        dotenv_path: str | Path | None = None,
     ) -> bytes:
         """Decrypt bytes data.
 
-        Supports ENV-based secret resolution for password:
+        Supports multiple secret reference formats:
             Filanti.decrypt_bytes(data, password="ENV:MY_PASSWORD")
+            Filanti.decrypt_bytes(data, password="$env:MY_PASSWORD")  # PowerShell
+            Filanti.decrypt_bytes(data, password="${MY_PASSWORD}")    # Shell-style
+            Filanti.decrypt_bytes(data, password="env.MY_PASSWORD")   # Dot notation
 
         Args:
             data: Encrypted data.
-            password: Password used for encryption. Supports ENV:VAR_NAME syntax.
+            password: Password used for encryption. Supports ENV reference syntax.
             key: Raw encryption key.
+            dotenv_path: Optional path to .env file to load secrets from.
 
         Returns:
             Decrypted bytes.
@@ -455,7 +535,7 @@ class Filanti:
         """
         if password is not None:
             # Resolve password from ENV if needed
-            resolved_password = resolve_secret(password)
+            resolved_password = resolve_secret(password, dotenv_path=dotenv_path)
             # Parse the encrypted data from bytes
             encrypted = EncryptedData.from_bytes(data)
             return _decrypt_bytes_with_password(encrypted, resolved_password)
@@ -920,6 +1000,8 @@ class Filanti:
         output: str | Path | None = None,
         password: str | bytes | None = None,
         recipient_id: str | None = None,
+        remove_source: bool = False,
+        secure_delete: bool = True,
     ) -> HybridDecryptResult:
         """Decrypt a hybrid encrypted file.
 
@@ -929,6 +1011,9 @@ class Filanti:
             output: Output path (default: removes .henc extension).
             password: Password if private key is encrypted.
             recipient_id: Optional recipient ID to select specific session key.
+            remove_source: If True, delete encrypted file after successful decryption.
+            secure_delete: If True and remove_source is True, securely overwrite
+                the encrypted file before deletion.
 
         Returns:
             HybridDecryptResult with output path and size.
@@ -943,6 +1028,13 @@ class Filanti:
                 "my-key.pem",
                 password="my-password"
             )
+
+            # Decrypt and remove encrypted file
+            Filanti.hybrid_decrypt(
+                "secret.txt.henc",
+                "my-key.pem",
+                remove_source=True
+            )
         """
         path = Path(path)
         if output:
@@ -957,6 +1049,15 @@ class Filanti:
 
         size = _hybrid_decrypt_file(path, out_path, private_key, password, recipient_id)
 
+        # Remove encrypted source file if requested
+        if remove_source:
+            from filanti.core.file_manager import get_file_manager
+            fm = get_file_manager()
+            if secure_delete:
+                fm.secure_delete(path)
+            else:
+                fm.delete(path)
+
         return HybridDecryptResult(output_path=out_path, size=size)
 
     @staticmethod