da

utils/__init__.py

@@ -1 +1,6 @@
-# This file ensures that the utils directory is treated as a Python package
+"""
+@file utils/__init__.py
+@brief Package initializer for utility helpers.
+@details Exposes helper modules used by OMG-Fuscator (encryption, junk generation,
+         and obfuscated name generation).
+"""

utils/encryption.py

@@ -1,18 +1,38 @@
+"""
+@file utils/encryption.py
+@brief String encryption utilities for OMG-Fuscator.
+@details Provides the StringEncryptor used by the obfuscation pipeline to transform
+         string literals into runtime-decrypted expressions, making static analysis
+         significantly harder.
+"""
+
 import base64
 import hashlib
 import random
 from typing import Tuple
 
 class StringEncryptor:
+    """
+    @brief Encrypts strings for obfuscation using layered XOR and Base85 encoding.
+    @details Produces both an encoded payload and Python code that reconstructs
+             the keys at runtime without embedding raw key bytes.
+    """
     def __init__(self, primary_key: bytes, secondary_key: bytes, salt: bytes):
+        """
+        @brief Initialize encryptor keys.
+        @param primary_key Primary XOR key bytes.
+        @param secondary_key Secondary XOR key bytes.
+        @param salt Salt bytes used to derive a per-string modifier.
+        """
         self.primary_key = primary_key
         self.secondary_key = secondary_key
         self.salt = salt
 
     def hide_byte(self, b: int) -> str:
         """
-        Obfuscates a single byte as a random arithmetic or bitwise expression.
-        Used in the string encryption code to hide key bytes.
+        @brief Obfuscate a single key byte into an arithmetic/bitwise expression.
+        @param b Input byte value in range [0, 255].
+        @return Python expression string that evaluates to the original byte at runtime.
         """
         pattern = random.randint(1, 5)
         if pattern == 1:
@@ -41,11 +61,12 @@ class StringEncryptor:
 
     def encrypt_string(self, s: str) -> Tuple[str, str, str]:
         """
-        Encrypts a string with a multi-layer XOR scheme
-        and base85-encodes the result. Returns:
-          - encoded string,
-          - the code snippet that re-creates the keys in Python,
-          - the hex digest for the 'modifier'.
+        @brief Encrypt a string with layered XOR and Base85 encoding.
+        @param s UTF-8 string to encrypt.
+        @return Tuple[str, str, str]:
+            - encoded: Base85 text of the encrypted payload
+            - key_setup: Python code that reconstructs keys at runtime
+            - modifier_hex: Hex string for the per-string modifier
         """
         data = s.encode('utf-8')
         modifier = hashlib.sha256(self.salt + data).digest()[:8]

utils/junk_gen.py

@@ -1,14 +1,29 @@
+"""
+@file utils/junk_gen.py
+@brief Junk code generation utilities for OMG-Fuscator.
+@details Generates random noise statements and multi-line snippets for obfuscation.
+"""
+
 import random
 import string
 from utils.name_gen import NameGenerator
 
 class JunkGenerator:
+    """
+    @brief Produces pseudo-random junk code.
+    @param name_generator Name generator used for variable identifiers.
+    """
     def __init__(self, name_generator: NameGenerator):
+        """
+        @brief Constructor.
+        @param name_generator NameGenerator instance used to create junk variable names.
+        """
         self.name_generator = name_generator
 
     def add_junk(self) -> str:
         """
-        Generates random multi-line junk code, used to pad the final output.
+        @brief Generate a random multi-line junk code snippet.
+        @return Python source string with one or more lines.
         """
         var1 = self.name_generator.generate_name()
         var2 = self.name_generator.generate_name()
@@ -36,7 +51,8 @@ class JunkGenerator:
 
     def generate_junk(self) -> str:
         """
-        Generates a single line of junk code.
+        @brief Generate a single-line junk statement.
+        @return Python source string for a single assignment or expression.
         """
         var_name = self.name_generator.generate_name()
         junk_code = [

utils/name_gen.py

@@ -1,14 +1,29 @@
+"""
+@file utils/name_gen.py
+@brief Obfuscated identifier name generator.
+@details Provides NameGenerator that yields high-entropy-looking identifiers
+         and ensures uniqueness across a transformation session.
+"""
 import itertools
 from typing import Iterator, Set
 
 class NameGenerator:
+    """
+    @brief Generates unique obfuscated identifiers.
+    @details Uses patterned Cartesian products to create long, confusing names and
+             tracks used names to avoid collisions.
+    """
     def __init__(self):
+        """
+        @brief Initialize internal iterator and used-name set.
+        """
         self._name_iterator = self._create_iterator()
         self.used_names = set()
     
     def _create_iterator(self) -> Iterator[str]:
         """
-        Generates obfuscated names like: vIl1lO0o0Z2z2...
+        @brief Iterator producing obfuscated identifier candidates.
+        @return Iterator[str] Infinite stream of names such as vIl1lO0o0Z2z2...
         """
         patterns = ['Il1l', 'O0o0', 'Z2z2', 'S5s5', 'B8b8', 'Q9q9']
         for length in itertools.count(2):  # Start with length=2, continue forever
@@ -17,7 +32,8 @@ class NameGenerator:
 
     def generate_name(self) -> str:
         """
-        Get a fresh unique variable name.
+        @brief Produce a fresh, unique obfuscated name.
+        @return str Name guaranteed not to have been produced before by this instance.
         """
         while True:
             candidate = next(self._name_iterator)