feat: Add advanced layout engine and encryption support

- Introduce LayoutEngine for token-stream based obfuscation that preserves
  formatting, comments, and string styles
- Add EncryptionManager for secure obfuscation with key-based encryption
- Enhance PythonObfuscator with layout preservation capabilities
- Improve CObfuscator symbol detection with better external symbol scanning
- Add comprehensive test coverage for new features
- Update CLI to support encryption options
- Refactor ImportAnalyzer to better handle protected identifiers
- Add .obf.c to .gitignore for C obfuscated files

Author: for13to1

.gitignore

@@ -69,6 +69,8 @@ Thumbs.db
 # Mistode specific
 *.obf.py
 *.res.py
+*.obf.c
+*.res.c
 *.map.json
 *.key
 

src/mistode/c.py

@@ -132,11 +132,11 @@ def _tokenize(self, text: str) -> Iterator[Match[str]]:
         """Yields regex matches for tokens in the C source code."""
         return self.TOKEN_PATTERN.finditer(text)
 
-    def _scan_for_undefined_symbols(self, source_code: str) -> Set[str]:
+    def _scan_for_external_symbols(self, source_code: str) -> Set[str]:
         """
-        Heuristic scanner to identify symbols that are used but NOT
-        defined in the file. Acts as a fallback when compiler tools are
-        unavailable, or as a primary analysis for simple cases.
+        Heuristic scanner to identify external symbols (used but not defined in file).
+        Acts as a fallback when compiler tools are unavailable, or as a primary
+        analysis for simple cases.
         """
         defined_symbols = set()
         all_identifiers = set()
@@ -304,7 +304,7 @@ def _identify_external_symbols(self, source_code: str) -> Set[str]:
                         pass
 
         # Method 2: Heuristic Fallback
-        return self._scan_for_undefined_symbols(source_code)
+        return self._scan_for_external_symbols(source_code)
 
     def _inject_source_as_comments(self, source_code: str, obfuscated_code: str) -> str:
         """
@@ -434,7 +434,7 @@ def obfuscate(self, source_code: str) -> str:
         # 3. Embed Metadata (Keys) - Kept for legacy compatibility
         # or if lossless restoration fails
         mapping_info = {
-            "twd": self.mm.mapping,
+            "identifier_mapping": self.mm.mapping,
             "comments": self.mm.comments,
             "files": self.mm.file_mapping,
             "encryption_key": self.mm.encryption_key,
@@ -481,7 +481,7 @@ def restore(self, source_code: str) -> str:
 
                 # Load metadata if not already loaded (or merge)
                 if not self.mm.mapping:
-                    self.mm.mapping = data.get("twd", {})
+                    self.mm.mapping = data.get("identifier_mapping", {})
                     self.mm.reverse_mapping = {v: k for k, v in self.mm.mapping.items()}
                     self.mm.comments = data.get("comments", {})
                     self.mm.file_mapping = data.get("files", {})

src/mistode/cli.py

@@ -23,6 +23,7 @@
 
 from .c import CObfuscator
 from .core import MappingManager, NameGenerator
+from .encrypt import EncryptionManager
 from .python import PythonObfuscator
 
 
@@ -44,8 +45,14 @@ class CLIError(Exception):
     pass
 
 
-class FileNotFoundError(CLIError):
-    pass
+class FileNotFound(CLIError):
+    """Custom FileNotFound to avoid conflict with built-in FileNotFoundError"""
+
+    def __init__(self, filepath: str = ""):
+        self.filepath = filepath
+        super().__init__(
+            f"File not found: {filepath}" if filepath else "File not found"
+        )
 
 
 class ObfuscationError(CLIError):
@@ -58,6 +65,7 @@ class Options:
     input_file: Path
     output_file: Optional[Path] = None
     key_file: Optional[Path] = None
+    password: Optional[str] = None
     seed: Optional[int] = None
     style: str = "similar"
     length: int = 16
@@ -69,9 +77,17 @@ class ObfuscationService:
     def __init__(self, options: Options):
         self.options = options
         self.mm = MappingManager()
-        self.gen = NameGenerator(
-            length=options.length, style=options.style, seed=options.seed
-        )
+        # If seed is not provided but password is, derive seed from password
+        seed = options.seed
+        if seed is None and options.password:
+            # Deterministic seed from password for consistent obfuscation
+            import hashlib
+
+            seed = int.from_bytes(
+                hashlib.sha256(options.password.encode()).digest()[:8], "big"
+            )
+
+        self.gen = NameGenerator(length=options.length, style=options.style, seed=seed)
         self.stats_data = {}
 
     def execute(self) -> None:
@@ -90,7 +106,9 @@ def _obfuscate(self) -> None:
         if options.language == Language.PYTHON:
             obfuscator = PythonObfuscator(self.mm, self.gen, options.input_file.name)
             key_path = str(options.key_file) if options.key_file else None
-            result = obfuscator.obfuscate(content, key_path)  # type: ignore
+            result = obfuscator.obfuscate(
+                content, key_path, encryption_key=options.password
+            )
         else:
             obfuscator = CObfuscator(self.mm, self.gen, options.input_file.name)
             result = obfuscator.obfuscate(content)
@@ -128,7 +146,9 @@ def _restore(self) -> None:
                     self.mm, self.gen, options.input_file.name
                 )
                 key_path = str(options.key_file) if options.key_file else None
-                result = obfuscator.restore(key_path, content)  # type: ignore
+                result = obfuscator.restore(
+                    key_path, content, encryption_key=options.password
+                )
             else:
                 obfuscator = CObfuscator(self.mm, self.gen, options.input_file.name)
                 result = obfuscator.restore(content)
@@ -146,25 +166,23 @@ def _restore(self) -> None:
     def _read_file(self, path: Path) -> str:
         try:
             return path.read_text(encoding="utf-8")
-        except FileNotFoundError:
-            raise FileNotFoundError(
+        except OSError:  # Catch file not found and other OS errors
+            raise FileNotFound(
                 f"❌ Error: Input file not found: {path}\n"
                 f"💡 Hint: Check if the file path is correct or use an absolute path"
             )
         except PermissionError:
-            raise FileNotFoundError(
+            raise FileNotFound(
                 f"❌ Error: Permission denied: {path}\n"
                 f"💡 Hint: Check file permissions or try running with appropriate rights"
             )
         except UnicodeDecodeError:
-            raise FileNotFoundError(
+            raise FileNotFound(
                 f"❌ Error: File encoding issue: {path}\n"
                 f"💡 Hint: Ensure the file is a valid text file with UTF-8 encoding"
             )
         except Exception as e:
-            raise FileNotFoundError(
-                f"❌ Error: Failed to read {path}\n" f"💡 Details: {e}"
-            )
+            raise FileNotFound(f"❌ Error: Failed to read {path}\n" f"💡 Details: {e}")
 
     def _write_file(self, path: Path, content: str) -> None:
         try:
@@ -189,7 +207,7 @@ def _write_file(self, path: Path, content: str) -> None:
     def _load_mapping(self, key_file: Path) -> None:
         try:
             self.mm.load_mapping(key_file)
-        except FileNotFoundError:
+        except OSError:  # Catch file not found and other OS errors
             raise ObfuscationError(
                 f"❌ Error: Key file not found: {key_file}\n"
                 f"💡 Hint: Ensure the key file exists or try restoration without --key (using embedded metadata)"
@@ -339,7 +357,10 @@ def _add_obfuscate_command(self, subparsers) -> None:
         )
         obf.add_argument("input_file", help="Path to input source file")
         obf.add_argument("--out", "-o", help="Path to output file")
-        obf.add_argument("--key", "-k", help="Path to key file")
+        obf.add_argument("--key", "-k", help="Path to key file (JSON map)")
+        obf.add_argument(
+            "--password", "-p", "--pwd", help="Password for encryption/decryption"
+        )
         obf.add_argument("--seed", "-s", type=int, help="Random seed")
         obf.add_argument(
             "--style",
@@ -368,7 +389,10 @@ def _add_restore_command(self, subparsers) -> None:
         )
         res.add_argument("input_file", help="Path to obfuscated file")
         res.add_argument("--out", "-o", help="Path to output file")
-        res.add_argument("--key", "-k", help="Path to key file")
+        res.add_argument("--key", "-k", help="Path to key file (JSON map)")
+        res.add_argument(
+            "--password", "-p", "--pwd", help="Password for encryption/decryption"
+        )
         res.add_argument(
             "--stats",
             action="store_true",
@@ -401,6 +425,11 @@ def _convert_to_options(self, raw) -> Options:
                 if hasattr(raw, "seed") and raw.seed is not None
                 else config.get("seed", None)
             ),
+            password=(
+                raw.password
+                if hasattr(raw, "password")
+                else config.get("password", None)
+            ),
             style=(
                 raw.style
                 if hasattr(raw, "style") and raw.style is not None
@@ -494,7 +523,7 @@ def run() -> None:
 
     try:
         service.execute()
-    except FileNotFoundError as e:
+    except FileNotFound as e:
         print(f"{e}")
         sys.exit(1)
     except ObfuscationError as e:

src/mistode/core.py

@@ -21,14 +21,12 @@
 class NameGenerator:
     def __init__(self, length: int = 16, style: str = "similar", seed=None):
         """
-        Encrypted token generator
+        Obfuscated token name generator.
 
         Args:
-            length: token length, range [8,32]
-            length: token length, range [8,32]
-            style: naming style - "similar" (visually similar characters),
-                   "random" (purely random)
-            seed: random seed
+            length: Token length (8-32 characters).
+            style: Naming style - "similar" (visually similar chars) or "random".
+            seed: Random seed for reproducible generation.
         """
         if length < 8 or length > 32:
             raise ValueError(f"Length must be between 8 and 32, current: {length}")
@@ -63,7 +61,7 @@ def __init__(self, length: int = 16, style: str = "similar", seed=None):
 
     def generate(self) -> str:
         """
-        Generate unique encrypted token
+        Generate unique obfuscated identifier
         """
         max_attempts = 100
         for attempt in range(max_attempts):
@@ -93,7 +91,7 @@ def _generate_single(self) -> str:
 
     def _generate_similar(self) -> str:
         """
-        Generate similar character style token
+        Generate similar character style identifier with random first character
         """
         first_char = self.rng.choice(self.random_letters)
 
@@ -199,10 +197,16 @@ def get_string_quote_types(self, filename):
     def register_file(self, original, obfuscated):
         self.file_mapping[obfuscated] = original
 
-    def load_mapping(self, filepath):
-        with open(filepath, "r") as f:
+    def load_mapping(self, filepath: str) -> None:
+        """
+        Load mapping data from JSON file.
+
+        Args:
+            filepath: Path to the mapping JSON file.
+        """
+        with open(filepath, "r", encoding="utf-8") as f:
             data = json.load(f)
-            self.mapping = data.get("twd", {})  # forward
+            self.mapping = data.get("identifier_mapping", {})
             self.reverse_mapping = {v: k for k, v in self.mapping.items()}
             self.comments = data.get("comments", {})
             self.file_mapping = data.get("files", {})
@@ -213,7 +217,7 @@ def save_mapping(self, filepath):
         with open(filepath, "w") as f:
             json.dump(
                 {
-                    "twd": self.mapping,
+                    "identifier_mapping": self.mapping,
                     "comments": self.comments,
                     "files": self.file_mapping,
                     "encryption_key": self.encryption_key,

src/mistode/encrypt.py

@@ -0,0 +1,78 @@
+"""
+Encryption Manager for Mistode
+Provides secure, key-based encryption for source chunks and metadata.
+"""
+
+import base64
+import hashlib
+from typing import Union
+
+
+class EncryptionManager:
+    """
+    Manages encryption and decryption of data using a user-provided key.
+    Uses a CTR-mode like stream cipher based on SHA-256 for high entropy.
+    """
+
+    def __init__(self, key: str):
+        """
+        Initialize with a string key.
+        The key is hashed to create a 32-byte master key.
+        """
+        if not key:
+            raise ValueError("Key cannot be empty")
+        # SHA-256 to get a fixed-length key from arbitrary string
+        self.key_hash = hashlib.sha256(key.encode("utf-8")).digest()
+
+    def _xor_cipher(self, data: bytes) -> bytes:
+        """
+        Encodes/Decodes data using a stream cipher.
+        Keystream is generated via SHA-256(Key + BlockCounter).
+        """
+        output = bytearray(len(data))
+        block_size = 32  # SHA-256 output size
+        num_blocks = (len(data) + block_size - 1) // block_size
+
+        for i in range(num_blocks):
+            # Generate keystream block: SHA256(Key + Counter)
+            # This ensures each block has a unique mask derived from the key
+            counter_bytes = i.to_bytes(8, "big")
+            keystream_block = hashlib.sha256(self.key_hash + counter_bytes).digest()
+
+            start = i * block_size
+            end = min(start + block_size, len(data))
+
+            for j in range(start, end):
+                # keystream_block index is (j - start)
+                output[j] = data[j] ^ keystream_block[j - start]
+
+        return bytes(output)
+
+    def encrypt(self, data: Union[str, bytes]) -> str:
+        """
+        Encrypt data and return base64 string.
+        """
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+
+        encrypted = self._xor_cipher(data)
+        return base64.b64encode(encrypted).decode("ascii")
+
+    def decrypt(self, data: str) -> bytes:
+        """
+        Decrypt base64 string and return bytes.
+        """
+        try:
+            encrypted = base64.b64decode(data)
+        except Exception:
+            raise ValueError("Invalid base64 input")
+
+        return self._xor_cipher(encrypted)
+
+    def get_seed(self) -> int:
+        """
+        Derive a deterministic integer seed from the key.
+        Used for seeding the random number generator for variable names.
+        """
+        # Take first 8 bytes of key hash and convert to int
+        return int.from_bytes(self.key_hash[:8], "big")