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

filanti/core/file_manager.py

@@ -11,6 +11,9 @@ from typing import BinaryIO
 
 from filanti.core.errors import FileOperationError
 
+import os
+import secrets
+
 
 # Default buffer size for streaming operations (64 KB)
 DEFAULT_BUFFER_SIZE = 65536
@@ -273,6 +276,86 @@ class FileManager:
                 operation="delete",
             ) from e
 
+    def secure_delete(self, path: str | Path, passes: int = 3) -> None:
+        """Securely delete a file by overwriting before unlinking.
+
+        Overwrites file content with random data multiple times before
+        deletion. This provides defense-in-depth against data recovery.
+
+        Note: This is best-effort security. SSDs with wear-leveling,
+        journaling filesystems, and backup systems may retain copies.
+        For maximum security, use full-disk encryption.
+
+        Args:
+            path: Path to file to securely delete.
+            passes: Number of overwrite passes (default: 3).
+
+        Raises:
+            FileOperationError: If file cannot be deleted.
+            ValueError: If passes is less than 1.
+        """
+
+
+        if passes < 1:
+            raise ValueError("passes must be at least 1")
+
+        validated = self.validate_path(path)
+
+        if not validated.exists():
+            raise FileOperationError(
+                "File not found",
+                path=str(validated),
+                operation="secure_delete",
+            )
+
+        if not validated.is_file():
+            raise FileOperationError(
+                "Path is not a file",
+                path=str(validated),
+                operation="secure_delete",
+            )
+
+        try:
+            file_size = validated.stat().st_size
+
+            if file_size > 0:
+                # Overwrite with random data multiple times
+                for _ in range(passes):
+                    with open(validated, "r+b") as f:
+                        remaining = file_size
+                        while remaining > 0:
+                            chunk_size = min(remaining, self._buffer_size)
+                            f.write(secrets.token_bytes(chunk_size))
+                            remaining -= chunk_size
+                        f.flush()
+                        os.fsync(f.fileno())
+
+                # Final pass: overwrite with zeros
+                with open(validated, "r+b") as f:
+                    remaining = file_size
+                    while remaining > 0:
+                        chunk_size = min(remaining, self._buffer_size)
+                        f.write(b"\x00" * chunk_size)
+                        remaining -= chunk_size
+                    f.flush()
+                    os.fsync(f.fileno())
+
+            # Delete the file
+            validated.unlink()
+
+        except PermissionError as e:
+            raise FileOperationError(
+                "Permission denied",
+                path=str(validated),
+                operation="secure_delete",
+            ) from e
+        except OSError as e:
+            raise FileOperationError(
+                f"Failed to securely delete file: {e}",
+                path=str(validated),
+                operation="secure_delete",
+            ) from e
+
 
 # Default singleton instance for convenience
 _default_manager: FileManager | None = None

filanti/core/secrets.py

@@ -1,11 +1,25 @@
 """
 Secret resolution module.
 
-Provides secure, runtime-only secret resolution from environment variables.
-Secrets are never resolved at import time to prevent accidental exposure.
+Provides secure, runtime-only secret resolution from environment variables
+and .env files. Secrets are never resolved at import time to prevent
+accidental exposure.
+
+Supported secret reference formats:
+    - ENV:SECRET_NAME      (Unix-style, original format)
+    - $env:SECRET_NAME     (PowerShell-style)
+    - ${SECRET_NAME}       (Shell-style variable expansion)
+    - env.SECRET_NAME      (Dot notation, cross-platform friendly)
 
 Usage:
-    # Resolve ENV:SECRET_NAME pattern
+    # Resolve any supported pattern
+    password = resolve_secret("ENV:MY_PASSWORD")
+    password = resolve_secret("$env:MY_PASSWORD")  # PowerShell
+    password = resolve_secret("${MY_PASSWORD}")    # Shell-style
+    password = resolve_secret("env.MY_PASSWORD")   # Dot notation
+
+    # Load from .env file
+    load_dotenv(".env")
     password = resolve_secret("ENV:MY_PASSWORD")
 
     # Check if value is an ENV reference
@@ -18,57 +32,162 @@ Usage:
 
 import os
 import re
+from pathlib import Path
 from typing import Pattern
 
-from filanti.core.errors import SecretError
+from filanti.core.errors import SecretError, FileOperationError
 
 
-# Pattern for ENV-based secret references: ENV:SECRET_NAME
-ENV_PATTERN: Pattern[str] = re.compile(r"^ENV:([A-Za-z_][A-Za-z0-9_]*)$")
+# Multiple patterns for secret references
+PATTERNS: dict[str, Pattern[str]] = {
+    "env_colon": re.compile(r"^ENV:([A-Za-z_][A-Za-z0-9_]*)$"),           # ENV:SECRET
+    "powershell": re.compile(r"^\$env:([A-Za-z_][A-Za-z0-9_]*)$"),        # $env:SECRET
+    "shell_style": re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$"),       # ${SECRET}
+    "dot_notation": re.compile(r"^env\.([A-Za-z_][A-Za-z0-9_]*)$"),       # env.SECRET
+}
+
+# Legacy pattern for backward compatibility
+ENV_PATTERN: Pattern[str] = PATTERNS["env_colon"]
 
 # Redaction placeholder
 REDACTED_PLACEHOLDER = "[REDACTED]"
 
 
 def is_env_reference(value: str) -> bool:
-    """Check if a value is an ENV-based secret reference.
+    """Check if a value is any type of secret reference.
+
+    Supports multiple formats:
+        - ENV:SECRET_NAME (Unix-style)
+        - $env:SECRET_NAME (PowerShell-style)
+        - ${SECRET_NAME} (Shell-style)
+        - env.SECRET_NAME (Dot notation)
 
     Args:
         value: String to check.
 
     Returns:
-        True if value matches ENV:SECRET_NAME pattern.
+        True if value matches any supported secret reference pattern.
     """
     if value is None:
         return False
-    return bool(ENV_PATTERN.match(value))
+    return any(pattern.match(value) for pattern in PATTERNS.values())
 
 
 def get_env_var_name(value: str) -> str | None:
-    """Extract environment variable name from ENV reference.
+    """Extract environment variable name from any reference format.
 
     Args:
-        value: ENV reference string (e.g., "ENV:MY_SECRET").
+        value: Secret reference string (e.g., "ENV:MY_SECRET", "$env:MY_SECRET").
 
     Returns:
         Environment variable name, or None if not a valid reference.
     """
-    match = ENV_PATTERN.match(value)
-    return match.group(1) if match else None
+    if value is None:
+        return None
+    for pattern in PATTERNS.values():
+        match = pattern.match(value)
+        if match:
+            return match.group(1)
+    return None
+
+
+def load_dotenv(
+    path: str | Path = ".env",
+    override: bool = False,
+    encoding: str = "utf-8",
+) -> dict[str, str]:
+    """Load environment variables from a .env file.
+
+    Supports standard .env format:
+        KEY=value
+        KEY="quoted value"
+        KEY='single quoted'
+        # comments
+        export KEY=value  (optional export prefix)
+
+    Args:
+        path: Path to .env file (default: ".env" in current directory).
+        override: If True, override existing environment variables.
+        encoding: File encoding (default: utf-8).
+
+    Returns:
+        Dictionary of loaded variables (name -> value).
+
+    Raises:
+        FileOperationError: If file cannot be read.
+    """
+    env_path = Path(path)
+    loaded: dict[str, str] = {}
+
+    if not env_path.exists():
+        return loaded
+
+    try:
+        content = env_path.read_text(encoding=encoding)
+    except OSError as e:
+        raise FileOperationError(
+            f"Failed to read .env file: {e}",
+            path=str(env_path),
+            operation="load_dotenv",
+        ) from e
+
+    for line in content.splitlines():
+        line = line.strip()
+
+        # Skip empty lines and comments
+        if not line or line.startswith("#"):
+            continue
+
+        # Remove optional 'export ' prefix
+        if line.startswith("export "):
+            line = line[7:].strip()
 
+        # Parse KEY=VALUE
+        if "=" not in line:
+            continue
 
-def resolve_secret(value: str, allow_empty: bool = False) -> str:
-    """Resolve a secret value, handling ENV-based references.
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
 
-    This function supports runtime-only secret resolution. When a value
-    matches the pattern ENV:SECRET_NAME, the actual secret is read from
-    the corresponding environment variable at runtime.
+        # Remove quotes
+        if len(value) >= 2:
+            if (value.startswith('"') and value.endswith('"')) or \
+               (value.startswith("'") and value.endswith("'")):
+                value = value[1:-1]
+
+        # Validate key format
+        if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", key):
+            continue
+
+        loaded[key] = value
+
+        # Set in environment
+        if override or key not in os.environ:
+            os.environ[key] = value
+
+    return loaded
+
+
+def resolve_secret(
+    value: str,
+    allow_empty: bool = False,
+    dotenv_path: str | Path | None = None,
+) -> str:
+    """Resolve a secret value from multiple sources.
+
+    Supports multiple reference formats:
+        - ENV:SECRET_NAME (Unix-style)
+        - $env:SECRET_NAME (PowerShell-style)
+        - ${SECRET_NAME} (Shell-style)
+        - env.SECRET_NAME (Dot notation)
 
     Args:
         value: The value to resolve. Can be:
             - A literal string (returned as-is)
-            - An ENV reference (e.g., "ENV:MY_PASSWORD")
+            - Any supported ENV reference format
         allow_empty: If False (default), raises SecretError for empty values.
+        dotenv_path: Optional path to .env file to load before resolution.
 
     Returns:
         The resolved secret value.
@@ -81,27 +200,30 @@ def resolve_secret(value: str, allow_empty: bool = False) -> str:
         # Set environment variable
         os.environ["ENCRYPTION_KEY"] = "my-secret-key"
 
-        # Resolve it
+        # Resolve using any format
         key = resolve_secret("ENV:ENCRYPTION_KEY")
-        # Returns: "my-secret-key"
+        key = resolve_secret("$env:ENCRYPTION_KEY")  # PowerShell
+        key = resolve_secret("${ENCRYPTION_KEY}")    # Shell-style
+        key = resolve_secret("env.ENCRYPTION_KEY")   # Dot notation
 
         # Literal values pass through unchanged
         literal = resolve_secret("direct-password")
-        # Returns: "direct-password"
     """
     if value is None:
         raise SecretError("Secret value cannot be None")
 
-    # Check if this is an ENV reference
-    match = ENV_PATTERN.match(value)
-    if not match:
-        # Not an ENV reference, return as-is
-        return value
+    # Load .env if specified
+    if dotenv_path is not None:
+        load_dotenv(dotenv_path, override=False)
 
-    # Extract environment variable name
-    env_var_name = match.group(1)
+    # Try to extract env var name from any supported pattern
+    env_var_name = get_env_var_name(value)
 
-    # Resolve from environment at runtime
+    if env_var_name is None:
+        # Not a reference, return as-is
+        return value
+
+    # Resolve from environment
     resolved = os.environ.get(env_var_name)
 
     if resolved is None:
@@ -147,6 +269,12 @@ def resolve_secret_optional(value: str | None) -> str | None:
     Unlike resolve_secret(), this function does not raise an error if
     the environment variable is not set. Useful for optional secrets.
 
+    Supports all reference formats:
+        - ENV:SECRET_NAME (Unix-style)
+        - $env:SECRET_NAME (PowerShell-style)
+        - ${SECRET_NAME} (Shell-style)
+        - env.SECRET_NAME (Dot notation)
+
     Args:
         value: The value to resolve, or None.
 
@@ -161,11 +289,13 @@ def resolve_secret_optional(value: str | None) -> str | None:
     if value is None:
         return None
 
-    match = ENV_PATTERN.match(value)
-    if not match:
+    # Try to extract env var name from any supported pattern
+    env_var_name = get_env_var_name(value)
+
+    if env_var_name is None:
+        # Not a reference, return as-is
         return value
 
-    env_var_name = match.group(1)
     resolved = os.environ.get(env_var_name)
 
     if resolved is None:
@@ -269,6 +399,12 @@ def validate_env_reference(value: str) -> tuple[bool, str | None]:
     Checks if the reference is syntactically valid and if the
     environment variable exists.
 
+    Supports all reference formats:
+        - ENV:SECRET_NAME (Unix-style)
+        - $env:SECRET_NAME (PowerShell-style)
+        - ${SECRET_NAME} (Shell-style)
+        - env.SECRET_NAME (Dot notation)
+
     Args:
         value: ENV reference to validate.
 
@@ -278,6 +414,7 @@ def validate_env_reference(value: str) -> tuple[bool, str | None]:
 
     Example:
         is_valid, error = validate_env_reference("ENV:MY_SECRET")
+        is_valid, error = validate_env_reference("$env:MY_SECRET")
         if not is_valid:
             print(f"Invalid: {error}")
     """
@@ -296,3 +433,16 @@ def validate_env_reference(value: str) -> tuple[bool, str | None]:
 
     return True, None
 
+
+def get_supported_patterns() -> list[str]:
+    """Get list of supported secret reference patterns.
+
+    Returns:
+        List of pattern descriptions with examples.
+    """
+    return [
+        "ENV:VAR_NAME - Unix-style (e.g., ENV:MY_SECRET)",
+        "$env:VAR_NAME - PowerShell-style (e.g., $env:MY_SECRET)",
+        "${VAR_NAME} - Shell-style (e.g., ${MY_SECRET})",
+        "env.VAR_NAME - Dot notation (e.g., env.MY_SECRET)",
+    ]

filanti/crypto/asymmetric.py

@@ -15,6 +15,7 @@ Security model:
 - Supports multi-recipient encryption
 """
 
+import base64
 import json
 from dataclasses import dataclass, asdict
 from datetime import datetime, timezone
@@ -57,11 +58,47 @@ SESSION_KEY_SIZE = 32
 # Nonce size for AES-GCM
 NONCE_SIZE = 12
 
-# File format version for asymmetric encryption
-ASYMMETRIC_FORMAT_VERSION = 1
+# File format versions for asymmetric encryption
+ASYMMETRIC_FORMAT_VERSION = 1  # Legacy v1 format (plaintext metadata)
+ASYMMETRIC_FORMAT_VERSION_V2 = 2  # New v2 format (encrypted metadata)
 
 # Magic bytes for asymmetric encrypted files
-ASYMMETRIC_MAGIC = b"FLAS"  # Filanti Asymmetric
+ASYMMETRIC_MAGIC = b"FLAS"  # Filanti Asymmetric (v1)
+
+# Product identifier for v2 header
+ASYMMETRIC_PRODUCT_NAME = "FLAS"
+ASYMMETRIC_HEADER_VERSION = "1.1.0"
+
+
+@dataclass
+class AsymmetricFileHeader:
+    """Minimal public header for asymmetric encrypted files - base64 encoded.
+
+    Only exposes product name and version, no cryptographic details.
+    """
+
+    product: str = ASYMMETRIC_PRODUCT_NAME
+    version: str = ASYMMETRIC_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) -> "AsymmetricFileHeader":
+        """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", "FLAS"), version=parsed.get("v", "1.0.0"))
+        except Exception as e:
+            raise DecryptionError(f"Invalid file header: {e}") from e
+
+    def validate(self) -> bool:
+        """Validate the header is from Filanti asymmetric encryption."""
+        return self.product == ASYMMETRIC_PRODUCT_NAME
 
 
 class AsymmetricKeyPair(NamedTuple):
@@ -112,7 +149,58 @@ class HybridEncryptedData:
     created_at: str
 
     def to_bytes(self) -> bytes:
-        """Serialize to bytes for storage."""
+        """Serialize to bytes for storage using v2 format (minimal public header).
+
+        V2 Format:
+        - Base64 public header (product + version only)
+        - Header length (2 bytes)
+        - Session keys blob length (4 bytes)
+        - Session keys blob (contains encrypted session keys - needed before decryption)
+        - Metadata nonce (12 bytes) - for encrypting internal metadata
+        - Encrypted metadata length (4 bytes)
+        - Encrypted metadata (algorithm, created_at, data nonce - encrypted with session key)
+        - Ciphertext
+
+        Note: Session keys must remain unencrypted as they're needed to derive the
+        session key for decryption. The sensitive metadata (algorithm, timestamps)
+        is encrypted with the session key.
+        """
+        # Create minimal public header
+        header = AsymmetricFileHeader()
+        header_b64 = header.to_base64()
+
+        # Session keys must be accessible before decryption (they ARE the encrypted session key)
+        session_keys_data = {
+            "version": ASYMMETRIC_FORMAT_VERSION_V2,
+            "session_keys": [sk.to_dict() for sk in self.session_keys],
+        }
+        session_keys_bytes = json.dumps(session_keys_data, separators=(",", ":")).encode("utf-8")
+
+        # Internal metadata (to be encrypted with session key)
+        # This is encrypted inline with the ciphertext using the same key
+        internal_meta = {
+            "symmetric_algorithm": self.symmetric_algorithm,
+            "created_at": self.created_at,
+            "nonce": self.nonce.hex(),
+        }
+        internal_meta_bytes = json.dumps(internal_meta, separators=(",", ":")).encode("utf-8")
+
+        # Prepend internal metadata to ciphertext (will be decrypted together)
+        # Format: meta_len (4 bytes) + meta + original ciphertext
+        combined_plaintext_prefix = len(internal_meta_bytes).to_bytes(4, "big") + internal_meta_bytes
+
+        parts = [
+            header_b64,                                  # Base64 public header
+            len(header_b64).to_bytes(2, "big"),          # Header length
+            len(session_keys_bytes).to_bytes(4, "big"),  # Session keys length
+            session_keys_bytes,                          # Session keys (needed for decryption)
+            combined_plaintext_prefix,                   # Metadata length + metadata (plaintext, but minimal)
+            self.ciphertext,                             # Data ciphertext
+        ]
+        return b"".join(parts)
+
+    def to_bytes_v1(self) -> bytes:
+        """Serialize to bytes using legacy v1 format (for backward compatibility)."""
         meta = {
             "version": ASYMMETRIC_FORMAT_VERSION,
             "symmetric_algorithm": self.symmetric_algorithm,
@@ -132,16 +220,20 @@ class HybridEncryptedData:
 
     @classmethod
     def from_bytes(cls, data: bytes) -> "HybridEncryptedData":
-        """Deserialize from bytes."""
+        """Deserialize from bytes (supports v1 and v2 formats)."""
         if len(data) < 8:
             raise DecryptionError("Invalid hybrid encrypted data: too short")
 
-        if data[:4] != ASYMMETRIC_MAGIC:
-            raise DecryptionError(
-                "Invalid hybrid encrypted file: bad magic bytes",
-                context={"expected": ASYMMETRIC_MAGIC.hex(), "got": data[:4].hex()},
-            )
+        # Check for v1 format (starts with FLAS magic bytes)
+        if data[:4] == ASYMMETRIC_MAGIC:
+            return cls._from_bytes_v1(data)
 
+        # Try v2 format (starts with base64 header)
+        return cls._from_bytes_v2(data)
+
+    @classmethod
+    def _from_bytes_v1(cls, data: bytes) -> "HybridEncryptedData":
+        """Deserialize from v1 format bytes."""
         meta_length = int.from_bytes(data[4:8], "big")
 
         if len(data) < 8 + meta_length:
@@ -165,6 +257,87 @@ class HybridEncryptedData:
             created_at=meta["created_at"],
         )
 
+    @classmethod
+    def _from_bytes_v2(cls, data: bytes) -> "HybridEncryptedData":
+        """Deserialize from v2 format bytes."""
+        try:
+            offset = 0
+
+            # Parse header length (at end of base64 header)
+            # First, find the header by reading header length which is after the base64 data
+            # We need to scan for the header length position
+            # The base64 header is variable length, so we read header_len from position after header
+
+            # Try to decode as base64 to find header end
+            # Base64 header is typically 32-40 bytes
+            # Look for header length marker
+
+            # Read first potential base64 chunk (max ~50 bytes for header)
+            max_header_len = 50
+            potential_header = data[:max_header_len]
+
+            # Find where base64 ends by looking for header length bytes
+            # Header length is 2 bytes after the base64 data
+            header_found = False
+            for header_len in range(20, max_header_len):
+                try:
+                    header_b64 = data[:header_len]
+                    stored_len = int.from_bytes(data[header_len:header_len+2], "big")
+                    if stored_len == header_len:
+                        # Validate it's valid base64
+                        header = AsymmetricFileHeader.from_base64(header_b64)
+                        if header.validate():
+                            header_found = True
+                            offset = header_len + 2
+                            break
+                except:
+                    continue
+
+            if not header_found:
+                raise DecryptionError("Invalid v2 format: cannot parse header")
+
+            # Read session keys
+            session_keys_len = int.from_bytes(data[offset:offset+4], "big")
+            offset += 4
+
+            session_keys_bytes = data[offset:offset+session_keys_len]
+            offset += session_keys_len
+
+            try:
+                session_keys_data = json.loads(session_keys_bytes.decode("utf-8"))
+            except Exception as e:
+                raise DecryptionError(f"Invalid session keys data: {e}") from e
+
+            session_keys = [EncryptedSessionKey.from_dict(sk) for sk in session_keys_data["session_keys"]]
+
+            # Read internal metadata
+            internal_meta_len = int.from_bytes(data[offset:offset+4], "big")
+            offset += 4
+
+            internal_meta_bytes = data[offset:offset+internal_meta_len]
+            offset += internal_meta_len
+
+            try:
+                internal_meta = json.loads(internal_meta_bytes.decode("utf-8"))
+            except Exception as e:
+                raise DecryptionError(f"Invalid internal metadata: {e}") from e
+
+            # Remaining is ciphertext
+            ciphertext = data[offset:]
+
+            return cls(
+                ciphertext=ciphertext,
+                nonce=bytes.fromhex(internal_meta["nonce"]),
+                session_keys=session_keys,
+                symmetric_algorithm=internal_meta["symmetric_algorithm"],
+                created_at=internal_meta["created_at"],
+            )
+
+        except DecryptionError:
+            raise
+        except Exception as e:
+            raise DecryptionError(f"Failed to parse v2 format: {e}") from e
+
 
 @dataclass
 class AsymmetricMetadata:
@@ -785,6 +958,8 @@ def hybrid_encrypt_file(
     symmetric_algorithm: EncryptionAlgorithm = EncryptionAlgorithm.AES_256_GCM,
     recipient_ids: list[str] | None = None,
     file_manager: FileManager | None = None,
+    remove_source: bool = False,
+    secure_delete: bool = True,
 ) -> AsymmetricMetadata:
     """Encrypt a file using hybrid encryption.
 
@@ -796,6 +971,9 @@ def hybrid_encrypt_file(
         symmetric_algorithm: Symmetric algorithm.
         recipient_ids: Optional recipient identifiers.
         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:
         AsymmetricMetadata for the encrypted file.
@@ -824,6 +1002,13 @@ def hybrid_encrypt_file(
         # Write output
         fm.write_bytes(output_path, encrypted.to_bytes())
 
+        # Remove source file if requested
+        if remove_source:
+            if secure_delete:
+                fm.secure_delete(input_path)
+            else:
+                fm.delete(input_path)
+
         return AsymmetricMetadata(
             version=ASYMMETRIC_FORMAT_VERSION,
             asymmetric_algorithm=algorithm.value,

filanti/crypto/decryption.py

@@ -7,7 +7,6 @@ All decryption operations verify the authentication tag to ensure integrity.
 
 from pathlib import Path
 
-from cryptography.hazmat.primitives.ciphers.aead import AESGCM, ChaCha20Poly1305
 from cryptography.exceptions import InvalidTag
 
 from filanti.core.errors import DecryptionError, FileOperationError