camouchat-browser 0.7.0__tar.gz

camouchat_browser-0.7.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: camouchat-browser
+Version: 0.7.0
+Summary: Plugin for CamouChat providing anti-detection browser management via Camoufox and Playwright.
+Keywords: browser-automation,stealth,camoufox,playwright,anti-detection,fingerprinting,browserforge
+Author: BITS-Rohit
+Author-email: BITS-Rohit <rohitguptaradheradhe123@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Requires-Dist: browserforge>=1.2.4
+Requires-Dist: camouchat-core
+Requires-Dist: camoufox[geoip]>=0.4.11
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: playwright>=1.58.0
+Requires-Dist: pyobjc-framework-quartz ; sys_platform == 'darwin'
+Maintainer: BITS-Rohit
+Maintainer-email: BITS-Rohit <rohitguptaradheradhe123@gmail.com>
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/CamouChat-Team
+Project-URL: Repository, https://github.com/CamouChat-Team/camouchat-browser
+Project-URL: Bug Tracker, https://github.com/CamouChat-Team/camouchat-browser/issues
+Project-URL: Changelog, https://github.com/CamouChat-Team/camouchat-browser/releases
+Description-Content-Type: text/markdown
+
+# CamouChat Browser 🦊
+
+A high-performance, stealth-oriented browser orchestration layer designed for the CamouChat ecosystem. Built on top of [Camoufox](https://camoufox.com/), it provides advanced anti-detection capabilities, hardware-level fingerprint spoofing, and robust session management.
+
+## Key Features
+
+- **Advanced Stealth**: Powered by [Camoufox](https://camoufox.com/) for industry-leading anti-bot bypass.
+- **Fingerprint Spoofing**: Deep integration with `browserforge` for authentic hardware and software headers.
+- **Session Isolation**: Automated profile management with persistent storage for cookies and local data.
+- **GeoIP & Proxy Ready**: Built-in support for residential proxies and automated GeoIP matching.
+- **Humanized Interaction**: Smooth mouse movements and typing patterns to maintain high stealth scores.
+
+## Installation
+
+Add to your project using `uv`:
+
+```bash
+uv add camouchat-browser
+```
+
+## Quick Start
+
+```python
+from camouchat_browser import BrowserConfig, CamoufoxBrowser, ProfileManager, BrowserForge
+from camouchat_core import Platform
+
+# 1. Setup Configuration
+config = BrowserConfig.from_dict({
+    "platform": Platform.WHATSAPP,
+    "headless": False,
+    "locale": "en-US",
+    "fingerprint_obj": BrowserForge()
+})
+
+# 2. Manage Profiles
+pm = ProfileManager(platform=Platform.WHATSAPP)
+profile = pm.get_profile(profile_id="stealth_user_1")
+
+# 3. Launch Browser
+browser = CamoufoxBrowser(config=config, profile=profile)
+page = await browser.get_page()
+
+await page.goto("https://check.camoufox.com")
+```
+
+## Documentation
+
+- [Browser Configuration](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/browser_config.md) - Finetuning stealth settings.
+- [Browser Engine](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/camoufox_browser.md) - Deep dive into Camoufox integration.
+- [Profile Management](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/profiles.md) - Managing sandboxes and encryption.
+- [Fingerprinting](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/BrowserForge.md) - hardware-level spoofing logic.
+
+## Roadmap
+
+- 🐳 **Docker Containerization**: Full headless Docker image with Xvfb, Camoufox binaries, and proxy-routing pre-configured out of the box (Targeting v0.8.0).
+
+## ⚖️ Security & Ethics
+
+CamouChat's strict policy regarding acceptable automation, anti-spam, and stealth disclaimers can be found in our central ecosystem hub:
+
+👉 **[SECURITY.md](https://github.com/CamouChat-Team/CamouChat/blob/main/SECURITY.md)**
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

camouchat_browser-0.7.0/README.md

@@ -0,0 +1,65 @@
+# CamouChat Browser 🦊
+
+A high-performance, stealth-oriented browser orchestration layer designed for the CamouChat ecosystem. Built on top of [Camoufox](https://camoufox.com/), it provides advanced anti-detection capabilities, hardware-level fingerprint spoofing, and robust session management.
+
+## Key Features
+
+- **Advanced Stealth**: Powered by [Camoufox](https://camoufox.com/) for industry-leading anti-bot bypass.
+- **Fingerprint Spoofing**: Deep integration with `browserforge` for authentic hardware and software headers.
+- **Session Isolation**: Automated profile management with persistent storage for cookies and local data.
+- **GeoIP & Proxy Ready**: Built-in support for residential proxies and automated GeoIP matching.
+- **Humanized Interaction**: Smooth mouse movements and typing patterns to maintain high stealth scores.
+
+## Installation
+
+Add to your project using `uv`:
+
+```bash
+uv add camouchat-browser
+```
+
+## Quick Start
+
+```python
+from camouchat_browser import BrowserConfig, CamoufoxBrowser, ProfileManager, BrowserForge
+from camouchat_core import Platform
+
+# 1. Setup Configuration
+config = BrowserConfig.from_dict({
+    "platform": Platform.WHATSAPP,
+    "headless": False,
+    "locale": "en-US",
+    "fingerprint_obj": BrowserForge()
+})
+
+# 2. Manage Profiles
+pm = ProfileManager(platform=Platform.WHATSAPP)
+profile = pm.get_profile(profile_id="stealth_user_1")
+
+# 3. Launch Browser
+browser = CamoufoxBrowser(config=config, profile=profile)
+page = await browser.get_page()
+
+await page.goto("https://check.camoufox.com")
+```
+
+## Documentation
+
+- [Browser Configuration](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/browser_config.md) - Finetuning stealth settings.
+- [Browser Engine](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/camoufox_browser.md) - Deep dive into Camoufox integration.
+- [Profile Management](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/profiles.md) - Managing sandboxes and encryption.
+- [Fingerprinting](https://github.com/CamouChat-Team/camouchat-browser/blob/main/docs/BrowserForge.md) - hardware-level spoofing logic.
+
+## Roadmap
+
+- 🐳 **Docker Containerization**: Full headless Docker image with Xvfb, Camoufox binaries, and proxy-routing pre-configured out of the box (Targeting v0.8.0).
+
+## ⚖️ Security & Ethics
+
+CamouChat's strict policy regarding acceptable automation, anti-spam, and stealth disclaimers can be found in our central ecosystem hub:
+
+👉 **[SECURITY.md](https://github.com/CamouChat-Team/CamouChat/blob/main/SECURITY.md)**
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

camouchat_browser-0.7.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "camouchat-browser"
+version = "0.7.0"
+description = "Plugin for CamouChat providing anti-detection browser management via Camoufox and Playwright."
+readme = "README.md"
+authors = [
+    { name = "BITS-Rohit", email = "rohitguptaradheradhe123@gmail.com" }
+]
+maintainers = [
+    { name = "BITS-Rohit", email = "rohitguptaradheradhe123@gmail.com" }
+]
+requires-python = ">=3.14"
+license = "MIT"
+keywords = [
+    "browser-automation",
+    "stealth",
+    "camoufox",
+    "playwright",
+    "anti-detection",
+    "fingerprinting",
+    "browserforge"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: AsyncIO",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Natural Language :: English",
+]
+dependencies = [
+    "browserforge>=1.2.4",
+    "camouchat-core",
+    "camoufox[geoip]>=0.4.11",
+    "platformdirs>=4.9.6",
+    "playwright>=1.58.0",
+    "pyobjc-framework-Quartz; sys_platform == 'darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/CamouChat-Team"
+Repository = "https://github.com/CamouChat-Team/camouchat-browser"
+"Bug Tracker" = "https://github.com/CamouChat-Team/camouchat-browser/issues"
+Changelog = "https://github.com/CamouChat-Team/camouchat-browser/releases"
+
+[tool.deptry]
+package_module_name_map = { "pyobjc-framework-Quartz" = "Quartz" }
+per_rule_ignores = { DEP002 = "pyobjc-framework-Quartz" }
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+[tool.uv.sources]
+camouchat-core = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "black>=26.3.1",
+    "deptry>=0.25.1",
+    "mypy>=1.20.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.10",
+    "twine>=6.2.0",
+]

camouchat_browser-0.7.0/src/camouchat_browser/__init__.py

@@ -0,0 +1,27 @@
+"""
+CamouChat Browser Plugin.
+
+This package provides high-performance, stealth-oriented browser management
+for the CamouChat ecosystem, leveraging Camoufox and BrowserForge for
+advanced anti-detection and session isolation.
+"""
+
+from .browser_config import BrowserConfig
+from .browserforge import BrowserForge
+from .camoufox_browser import CamoufoxBrowser
+from .directory import DirectoryManager
+from .exceptions import BrowserException
+from .profile_info import ProfileInfo
+from .profile_manager import ProfileManager
+
+# Todo , adding logger later
+
+__all__ = [
+    "BrowserForge",
+    "BrowserConfig",
+    "DirectoryManager",
+    "ProfileInfo",
+    "ProfileManager",
+    "CamoufoxBrowser",
+    "BrowserException",
+]

camouchat_browser-0.7.0/src/camouchat_browser/browser_config.py

@@ -0,0 +1,99 @@
+"""
+CamouBrowser Config.
+Pass this config to the CamouBrowser
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional
+
+from camouchat_core import Platform
+
+from .browserforge import BrowserForge
+
+
+@dataclass
+class BrowserConfig:
+    """
+    Config dataclass for browser.
+    """
+
+    platform: Platform
+    locale: str
+    enable_cache: bool
+    headless: bool
+    fingerprint_obj: BrowserForge
+    geoip: bool = True
+    proxy: Optional[Dict[str, str]] = None
+    prefs: Optional[Dict[str, bool]] = None
+    addons: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> BrowserConfig:
+        """
+        Creates a BrowserConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing configuration parameters.
+                 - platform: Target platform (e.g., Platform.WHATSAPP)
+                 - locale: Browser locale (e.g., "en-US")
+                 - enable_cache: Whether to use browser cache
+                 - headless: Whether to run in headless mode
+                 - geoip: Whether to use GeoIP spoofing (default: True)
+                 - proxy: Proxy configuration dictionary (server, username, password)
+                 - prefs: Firefox user preferences
+                 - addons: List of absolute paths to extensions
+                 - fingerprint_obj: BrowserForgeCapable instance
+        """
+        return cls(
+            platform=data.get("platform", Platform.WHATSAPP),
+            locale=data.get("locale", "en-US"),
+            enable_cache=data.get("enable_cache", False),
+            headless=data.get("headless", False),
+            prefs=data.get("prefs", {}),
+            addons=data.get("addons", []),
+            fingerprint_obj=data["fingerprint_obj"],
+            geoip=data.get("geoip", True),
+            proxy=data.get("proxy"),
+        )
+
+    def __str__(self):
+        return f"""
+            Platform: {self.platform}
+            Locale: {self.locale}
+            EnableCache: {self.enable_cache}
+            Headless: {self.headless}
+            Fingerprint: {self.fingerprint_obj!r} # Need to check for the fingerprint's __repr__
+            geoip: {self.geoip}
+            Proxy: {self.proxy}
+            Preferences: {self.prefs}
+            Addons: {self.addons}
+            """
+
+    def __repr__(self):
+        return (
+            f"BrowserConfig("
+            f"platform={self.platform}, "
+            f"locale='{self.locale}', "
+            f"headless={self.headless}, "
+            f"geoip={self.geoip}, "
+            f"fingerprint_obj={self.fingerprint_obj!r}"
+            f")"
+        )
+
+    def to_dict(self) -> Dict:
+        """
+        Serializes BrowserConfig to a dictionary.
+        """
+        return {
+            "platform": self.platform,
+            "locale": self.locale,
+            "enable_cache": self.enable_cache,
+            "headless": self.headless,
+            "geoip": self.geoip,
+            "proxy": self.proxy,
+            "prefs": self.prefs,
+            "addons": self.addons,
+            "fingerprint": {"provider": "browserforge"},
+        }

camouchat_browser-0.7.0/src/camouchat_browser/browser_logger.py

@@ -0,0 +1,15 @@
+from typing import Optional, Union
+from camouchat_core import LoggerFactory
+
+
+def get_profile_browser_logger(
+    name: str, profile_id: str = "GLOBAL", level: Optional[Union[int, str]] = None
+):
+    """Returns a logger specialized for browser operations with profile context."""
+    return LoggerFactory.get_logger(
+        name=name, platform="BROWSER", profile_id=profile_id, level=level
+    )
+
+
+# Default logger for the module
+logger = get_profile_browser_logger("browser_init")

camouchat_browser-0.7.0/src/camouchat_browser/browserforge.py

@@ -0,0 +1,238 @@
+"""
+BrowserForge fingerprint management module.
+
+This module provides hardware-level fingerprinting capabilities using the
+browserforge library, ensuring consistent and stealthy browser identities
+that match the host's actual display dimensions.
+"""
+
+import json
+import os
+import pickle
+from logging import Logger, LoggerAdapter
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+from browserforge.fingerprints import Fingerprint, FingerprintGenerator
+from camouchat_core import Platform
+
+from .browser_logger import logger
+from .directory import DirectoryManager
+from .exceptions import BrowserException
+from .profile_info import ProfileInfo
+
+
+class BrowserForge:
+    """
+    Manages browser fingerprint generation and persistence.
+
+    Uses the browserforge library to create authentic hardware/software signatures.
+    Fingerprints are tied to ProfileInfo objects to ensure identity consistency
+    across multiple sessions and avoid detection by screen-size mismatch.
+    """
+
+    log: Union[Logger, LoggerAdapter]
+
+    def __init__(self, log: Optional[Union[Logger, LoggerAdapter]] = None) -> None:
+        self.log = log or logger
+
+    def get_fg(self, profile: ProfileInfo) -> Fingerprint:
+        """
+        If old fingerprint exists -> returns that fingerprint.
+        Else creates new fingerprint.
+        :param profile: ProfileInfo instance
+        :return: Fingerprint
+        """
+        fingerprint_path: Path = profile.fingerprint_path
+        if fingerprint_path.exists():
+            if os.stat(fingerprint_path).st_size > 0:
+                with open(fingerprint_path, "rb") as fh:
+                    fg = pickle.load(fh)
+            else:
+                existing_fgs = self._get_all_existing_fingerprints(profile.platform)
+                fg = self.__gen_fg__(avoid=existing_fgs)
+                if fg is not None:
+                    with open(fingerprint_path, "wb") as fh:
+                        pickle.dump(fg, fh)
+            return fg
+        else:
+            raise BrowserException("path given does not exist")
+
+    def _get_all_existing_fingerprints(self, platform: Platform) -> list[Fingerprint]:
+        """
+        Scans all platforms and profiles to collect existing fingerprints.
+        :return: list of Fingerprint objects
+        """
+
+        dm = DirectoryManager()
+        fingerprints: list[Fingerprint] = []
+
+        platform_dir = dm.get_platform_dir(platform)
+        if not platform_dir.exists():
+            return fingerprints
+
+        for profile_dir in platform_dir.iterdir():
+            if not profile_dir.is_dir():
+                continue
+
+            fg_path = profile_dir / "fingerprint.pkl"
+            if fg_path.exists() and fg_path.stat().st_size > 0:
+                try:
+                    with open(fg_path, "rb") as fh:
+                        fg = pickle.load(fh)
+                        fingerprints.append(fg)
+                except Exception as e:
+                    self.log.warning(f"Could not load fingerprint from {fg_path}: {e}")
+
+        return fingerprints
+
+    def __gen_fg__(self, avoid: Optional[list[Fingerprint]] = None) -> Fingerprint:
+        """
+        Generates a new fingerprint.
+        :param avoid: Optional list of fingerprints to avoid
+        :return: Fingerprint
+        """
+        gen = FingerprintGenerator()
+        real_w, real_h = BrowserForge.get_screen_size()
+        tolerance = 0.1
+        attempt = 0
+        avoid = avoid or []
+
+        if real_w <= 0 or real_h <= 0:
+            raise BrowserException("Invalid real screen dimensions")
+
+        fg: Fingerprint
+        while True:
+            fg = gen.generate()
+            w, h = fg.screen.width, fg.screen.height
+            attempt += 1
+
+            if (
+                abs(w - real_w) / real_w < tolerance
+                and abs(h - real_h) / real_h < tolerance
+            ):
+                if fg in avoid:
+                    if self.log:
+                        self.log.warning(
+                            f"🔁 Generated fingerprint already exists in another profile. Regenerating... (attempt {attempt})"
+                        )
+                    if attempt < 30:
+                        continue
+
+                if self.log:
+                    self.log.info(f"✅ Fingerprint screen OK: {w}x{h}")
+                break
+
+            if self.log:
+                self.log.warning(
+                    f"🔁 Invalid fingerprint screen ({w}x{h}) vs real ({real_w}x{real_h}). Regenerating... ({attempt})"
+                )
+
+            if attempt >= 10:
+                if self.log:
+                    self.log.warning(
+                        "⚠️ Using last generated fingerprint after 10 attempts"
+                    )
+                break
+
+        return fg
+
+    @staticmethod
+    def get_screen_size() -> Tuple[int, int]:
+        """
+        Returns the width and height of the primary display in pixels.
+        Supports Windows, Linux (X11), and macOS.
+        """
+        import platform
+
+        system = platform.system()
+
+        # ---------------- Windows ----------------
+        if system == "Windows":
+            try:
+                import ctypes
+
+                user32 = ctypes.windll.user32  # type: ignore[attr-defined]
+                try:
+                    user32.SetProcessDPIAware()
+                except Exception:
+                    pass  # older Windows versions
+
+                return user32.GetSystemMetrics(0), user32.GetSystemMetrics(1)
+
+            except Exception as e:
+                raise BrowserException("Windows screen size detection failed") from e
+
+        # ---------------- Linux ----------------
+        elif system == "Linux":
+            try:
+                import subprocess
+
+                out = subprocess.check_output(
+                    ["xdpyinfo"], stderr=subprocess.DEVNULL
+                ).decode()
+
+                for line in out.splitlines():
+                    if "dimensions:" in line:
+                        dims = line.split()[1].split("x")
+                        return int(dims[0]), int(dims[1])
+
+                raise BrowserException("xdpyinfo did not return screen dimensions")
+
+            except Exception as e:
+                raise BrowserException("Linux screen size detection failed") from e
+
+        # ---------------- macOS ----------------
+        elif system == "Darwin":
+            try:
+                import Quartz  # type: ignore[import-not-found]
+            except ImportError as e:
+                raise BrowserException("Quartz not available on macOS") from e
+
+            display = Quartz.CGMainDisplayID()
+            return (
+                Quartz.CGDisplayPixelsWide(display),
+                Quartz.CGDisplayPixelsHigh(display),
+            )
+
+        # ---------------- Unsupported OS ----------------
+        else:
+            raise BrowserException(
+                f"Unsupported OS for screen size detection: {system}"
+            )
+
+    @staticmethod
+    def get_fingerprint_as_dict(profile: ProfileInfo) -> dict:
+        """
+        Auto-Configure path to check & return data .
+        :param profile: ProfileInfo
+        :return: dict
+        """
+        saved_fingerprint_path: Path = profile.fingerprint_path
+
+        if not saved_fingerprint_path.exists():
+            raise BrowserException("saved_fingerprint_path does not exist")
+
+        if not saved_fingerprint_path.is_file():
+            raise BrowserException("saved_fingerprint_path is not a file")
+
+        if os.stat(saved_fingerprint_path).st_size == 0:
+            raise BrowserException("saved_fingerprint_path is empty")
+
+        try:
+            with open(saved_fingerprint_path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            if not isinstance(data, dict):
+                raise BrowserException("Fingerprint JSON is not a valid dict")
+
+            return data
+
+        except json.JSONDecodeError as e:
+            raise BrowserException(f"Invalid fingerprint JSON format: {e}")
+
+        except Exception as e:
+            raise BrowserException(f"Failed to load fingerprint JSON: {e}")
+
+    def __repr__(self):
+        return f"BrowserForge(log={type(self.log).__name__})"