phonsint 0.1.0__tar.gz

phonsint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phonsint-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: phonsint
+Version: 0.1.0
+Summary: High-throughput silent phone number OSINT suite for platform footprinting, profile enrichment, and masked email discovery
+Keywords: osint,phone-osint,reconnaissance,security,threat-intelligence,footprinting,identity-enrichment,metadata-extraction
+Author-email: Kaif <kaifcodec@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+License-File: LICENSE
+Requires-Dist: phonenumbers>=8.13.0
+Requires-Dist: httpx[http2]>=0.27.0,<0.29.0
+Requires-Dist: curl_cffi>=0.7.0,<1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: colorama>=0.4.0,<1.0.0
+Requires-Dist: pytest>=7.0.0 ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: mypy ; extra == "dev"
+Project-URL: Bug Tracker, https://github.com/kaifcodec/phonsint/issues
+Project-URL: Homepage, https://github.com/kaifcodec/phonsint
+Project-URL: Repository, https://github.com/kaifcodec/phonsint.git
+Provides-Extra: dev
+
+# phonsint
+<img width="1713" height="420" alt="phonsint-banner" src="https://github.com/user-attachments/assets/a76a73a2-8aac-4813-a265-6802b2230eb0" />
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-0.1.0-blueviolet?style=for-the-badge&logo=github" />
+  <img src="https://img.shields.io/badge/Tested%20on-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Termux-black?style=for-the-badge" />
+</p>
+
+<p align="center">
+  <strong>High-Throughput Silent Phone Number OSINT & Identity Footprinting Suite</strong><br>
+  <em>Uncover account registrations, masked emails, display names, and profile photos across major platforms—without ever dispatching an SMS or alerting the target.</em>
+</p>
+
+---
+
+## ⚡ What is phonsint?
+
+Most phone number tools stop at basic format parsing or risk blowing an investigation by triggering loud 2FA/SMS verification codes to the target's mobile device.
+
+**phonsint** is engineered for **silent, high-fidelity reconnaissance**. It interrogates pre-authentication discovery endpoints, recovery validation flows, and cryptographic challenge APIs (such as Meta LOX proof-of-work) to determine account existence and extract rich profile metadata—**completely silently**.
+
+---
+
+## ✨ Key Capabilities
+
+* **Guaranteed Silent Operation**: Exploits unauthenticated query endpoints and pre-dispatch recovery flows that **never send SMS verification codes or push notifications** to the target.
+* **Deep Identity Enrichment**:
+  * 📧 **Masked Email Addresses**: Surfaces linked emails (e.g. `j******e@gmail.com`) associated with the phone number.
+  * 👤 **Full Display Names**: Pulls account owner names from public platform recovery APIs.
+  * 🖼️ **High-Resolution Avatars**: Extracts direct CDN profile photo URLs without logging in.
+  * 🏢 **Tenant & Region Routing**: Identifies regional datacenters (e.g., Zoho US, EU, IN, CN, JP).
+* **High-Throughput Concurrency**: Built with Python `asyncio` and `curl_cffi` for browser TLS fingerprint impersonation (bypasses Cloudflare, Akamai, and Shape Security without heavy headless browsers).
+* **Zero False Positives**: Uses strict, dual-state validation markers (matching the design philosophy of [`user-scanner`](https://github.com/kaifcodec/user-scanner)).
+*  **Multi-Format Reports**: Automated structured exports to **JSON** and **CSV** for immediate ingestion into investigation pipelines.
+
+---
+
+## 🖥️ Live Terminal Preview
+
+```text
+Checking phone: +14155552671
+
+== SOCIAL SITES ==
+[✔] Facebook (+14155552671) [Registered]
+    ├── name: John Doe
+    ├── masked_email: j******e@gmail.com
+    └── avatar: https://scontent.xx.fbcdn.net/v/t39.30808-1/s200x200/412...
+
+[✔] Instagram (+14155552671) [Registered]
+    └── contact_point: Phone Number Verified
+
+== AUTH SITES ==
+[✔] Microsoft (+14155552671) [Registered]
+    └── auth_type: Live ID / Account Exists
+
+== SHOPPING SITES ==
+[✔] Amazon (+14155552671) [Registered]
+    └── claim_endpoint: Active Sign-in Route
+
+== SUMMARY ==
+Total Sites Scanned: 5
+Registered / Found:  4
+```
+
+---
+
+## 🚀 Installation
+
+### 🐍 Via Virtual Environment (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/kaifcodec/phonsint.git
+cd phonsint
+
+# Create and activate virtual environment
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1
+
+# Install dependencies and package in editable mode
+pip install -e .
+```
+
+### 📦 Direct Installation
+
+```bash
+pip install phonsint
+```
+
+---
+
+## 💻 Usage Guide
+
+### 1. Standard Target Scan (E.164 Format)
+
+```bash
+phonsint -p +14155552671
+```
+
+### 2. Scanning Local Format Numbers with Default Region
+
+If a target number does not include an international `+` country prefix, specify the default ISO country code:
+
+```bash
+phonsint -p 07911123456 -r GB
+phonsint -p 9876543210 -r IN
+```
+
+### 3. Targeted Category & Module Filtering
+
+```bash
+# Scan authentication providers only (e.g., Microsoft)
+phonsint -p +14155552671 -c auth
+
+# Scan specific platforms
+phonsint -p +14155552671 -m facebook,instagram
+
+# List all available modules and categories in a clean table
+phonsint -l
+```
+
+### 4. Verbose Mode & Exporting Results
+
+```bash
+# Show all results including unregistered platforms and diagnostic reasons
+phonsint -p +14155552671 --all -v
+
+# Export results to JSON or CSV
+phonsint -p +14155552671 -o report.json
+phonsint -p +14155552671 -f csv -o report.csv
+```
+
+---
+
+## 🛡️ OPSEC & Silent-by-Default Guarantee
+
+In phone OSINT, accidental SMS verification codes sent to the target's phone are a critical operational failure. `phonsint` operates **100% silently by default**, targeting pre-dispatch query endpoints, session credential checks, and unauthenticated recovery validations that **do not dispatch SMS messages**.
+
+Any module that could potentially trigger a notification is registered under `LOUD_MODULES` in `phonsint/core/helpers.py` and will be automatically skipped unless the user explicitly passes `--allow-loud`.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Adding a new platform check takes around ~30 lines of clean Python. Check out **[CONTRIBUTING.md](CONTRIBUTING.md)** for developer conventions, validator signatures, and instructions.
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**.
+

phonsint-0.1.0/README.md

@@ -0,0 +1,151 @@
+# phonsint
+<img width="1713" height="420" alt="phonsint-banner" src="https://github.com/user-attachments/assets/a76a73a2-8aac-4813-a265-6802b2230eb0" />
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-0.1.0-blueviolet?style=for-the-badge&logo=github" />
+  <img src="https://img.shields.io/badge/Tested%20on-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Termux-black?style=for-the-badge" />
+</p>
+
+<p align="center">
+  <strong>High-Throughput Silent Phone Number OSINT & Identity Footprinting Suite</strong><br>
+  <em>Uncover account registrations, masked emails, display names, and profile photos across major platforms—without ever dispatching an SMS or alerting the target.</em>
+</p>
+
+---
+
+## ⚡ What is phonsint?
+
+Most phone number tools stop at basic format parsing or risk blowing an investigation by triggering loud 2FA/SMS verification codes to the target's mobile device.
+
+**phonsint** is engineered for **silent, high-fidelity reconnaissance**. It interrogates pre-authentication discovery endpoints, recovery validation flows, and cryptographic challenge APIs (such as Meta LOX proof-of-work) to determine account existence and extract rich profile metadata—**completely silently**.
+
+---
+
+## ✨ Key Capabilities
+
+* **Guaranteed Silent Operation**: Exploits unauthenticated query endpoints and pre-dispatch recovery flows that **never send SMS verification codes or push notifications** to the target.
+* **Deep Identity Enrichment**:
+  * 📧 **Masked Email Addresses**: Surfaces linked emails (e.g. `j******e@gmail.com`) associated with the phone number.
+  * 👤 **Full Display Names**: Pulls account owner names from public platform recovery APIs.
+  * 🖼️ **High-Resolution Avatars**: Extracts direct CDN profile photo URLs without logging in.
+  * 🏢 **Tenant & Region Routing**: Identifies regional datacenters (e.g., Zoho US, EU, IN, CN, JP).
+* **High-Throughput Concurrency**: Built with Python `asyncio` and `curl_cffi` for browser TLS fingerprint impersonation (bypasses Cloudflare, Akamai, and Shape Security without heavy headless browsers).
+* **Zero False Positives**: Uses strict, dual-state validation markers (matching the design philosophy of [`user-scanner`](https://github.com/kaifcodec/user-scanner)).
+*  **Multi-Format Reports**: Automated structured exports to **JSON** and **CSV** for immediate ingestion into investigation pipelines.
+
+---
+
+## 🖥️ Live Terminal Preview
+
+```text
+Checking phone: +14155552671
+
+== SOCIAL SITES ==
+[✔] Facebook (+14155552671) [Registered]
+    ├── name: John Doe
+    ├── masked_email: j******e@gmail.com
+    └── avatar: https://scontent.xx.fbcdn.net/v/t39.30808-1/s200x200/412...
+
+[✔] Instagram (+14155552671) [Registered]
+    └── contact_point: Phone Number Verified
+
+== AUTH SITES ==
+[✔] Microsoft (+14155552671) [Registered]
+    └── auth_type: Live ID / Account Exists
+
+== SHOPPING SITES ==
+[✔] Amazon (+14155552671) [Registered]
+    └── claim_endpoint: Active Sign-in Route
+
+== SUMMARY ==
+Total Sites Scanned: 5
+Registered / Found:  4
+```
+
+---
+
+## 🚀 Installation
+
+### 🐍 Via Virtual Environment (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/kaifcodec/phonsint.git
+cd phonsint
+
+# Create and activate virtual environment
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1
+
+# Install dependencies and package in editable mode
+pip install -e .
+```
+
+### 📦 Direct Installation
+
+```bash
+pip install phonsint
+```
+
+---
+
+## 💻 Usage Guide
+
+### 1. Standard Target Scan (E.164 Format)
+
+```bash
+phonsint -p +14155552671
+```
+
+### 2. Scanning Local Format Numbers with Default Region
+
+If a target number does not include an international `+` country prefix, specify the default ISO country code:
+
+```bash
+phonsint -p 07911123456 -r GB
+phonsint -p 9876543210 -r IN
+```
+
+### 3. Targeted Category & Module Filtering
+
+```bash
+# Scan authentication providers only (e.g., Microsoft)
+phonsint -p +14155552671 -c auth
+
+# Scan specific platforms
+phonsint -p +14155552671 -m facebook,instagram
+
+# List all available modules and categories in a clean table
+phonsint -l
+```
+
+### 4. Verbose Mode & Exporting Results
+
+```bash
+# Show all results including unregistered platforms and diagnostic reasons
+phonsint -p +14155552671 --all -v
+
+# Export results to JSON or CSV
+phonsint -p +14155552671 -o report.json
+phonsint -p +14155552671 -f csv -o report.csv
+```
+
+---
+
+## 🛡️ OPSEC & Silent-by-Default Guarantee
+
+In phone OSINT, accidental SMS verification codes sent to the target's phone are a critical operational failure. `phonsint` operates **100% silently by default**, targeting pre-dispatch query endpoints, session credential checks, and unauthenticated recovery validations that **do not dispatch SMS messages**.
+
+Any module that could potentially trigger a notification is registered under `LOUD_MODULES` in `phonsint/core/helpers.py` and will be automatically skipped unless the user explicitly passes `--allow-loud`.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Adding a new platform check takes around ~30 lines of clean Python. Check out **[CONTRIBUTING.md](CONTRIBUTING.md)** for developer conventions, validator signatures, and instructions.
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**.

phonsint-0.1.0/phonsint/__init__.py

@@ -0,0 +1,5 @@
+"""
+phonsint - Advanced Silent Phone Reconnaissance & Identity Footprinting Suite
+"""
+
+__version__ = "0.1.0"

phonsint-0.1.0/phonsint/__main__.py

@@ -0,0 +1,150 @@
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from colorama import Fore, Style, init
+
+from phonsint import __version__
+from phonsint.core.helpers import ScanConfig, load_categories, load_modules
+from phonsint.core.orchestrator import run_scan
+from phonsint.core.parser import parse_phone_number
+from rich.console import Console
+from rich.table import Table
+
+init(autoreset=True)
+console = Console()
+
+BANNER = rf"""{Fore.CYAN}
+    ____  __                      _       __ 
+   / __ \/ /_  ____  ____  _____ (_)___  / /_
+  / /_/ / __ \/ __ \/ __ \/ ___// / __ \/ __/
+ / ____/ / / / /_/ / / / (__  )/ / / / / /_  
+/_/   /_/ /_/\____/_/ /_/____//_/_/ /_/\__/  
+{Fore.LIGHTBLACK_EX}   phonsint v{__version__} | Silent Phone Reconnaissance & Intelligence Suite
+{Style.RESET_ALL}"""
+
+
+def print_banner() -> None:
+    print(BANNER)
+
+
+
+
+def list_modules() -> None:
+    print_banner()
+    categories = load_categories()
+    if not categories:
+        print(f"{Fore.YELLOW}[!] No modules found.{Style.RESET_ALL}")
+        return
+
+    table = Table(title="[bold cyan]Available Scan Modules[/bold cyan]", border_style="cyan")
+    table.add_column("Category", style="magenta", width=18)
+    table.add_column("Module", style="green", width=22)
+    table.add_column("Path", style="dim white")
+
+    for cat_name, cat_path in sorted(categories.items()):
+        mods = load_modules(cat_path)
+        for m in mods:
+            table.add_row(cat_name.capitalize(), m.__name__.split(".")[-1], str(m.__file__))
+
+    console.print(table)
+
+
+def export_results(results, file_path: str, fmt: str = "json") -> None:
+    out = Path(file_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    if fmt == "csv" or out.suffix.lower() == ".csv":
+        with open(out, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            writer.writerow(["site_name", "category", "phone", "status", "url", "extra", "media", "reason"])
+            for r in results:
+                writer.writerow([
+                    r.site_name,
+                    r.category,
+                    r.phone,
+                    r.status.to_label(),
+                    r.url,
+                    json.dumps(r.extra) if r.extra else "",
+                    json.dumps(r.media) if r.media else "",
+                    r.reason or "",
+                ])
+    else:
+        with open(out, "w", encoding="utf-8") as f:
+            json.dump([r.to_dict() for r in results], f, indent=2)
+
+    print(f"\n{Fore.GREEN}[+] Results successfully exported to: {out}{Style.RESET_ALL}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="phonsint",
+        description="phonsint: High-Throughput Silent Phone Number Reconnaissance & Identity Footprinting",
+    )
+    parser.add_argument("-p", "--phone", help="Target phone number (e.g. +14155552671)")
+    parser.add_argument("-r", "--region", help="Default ISO country code if number lacks '+' prefix (e.g. US, GB, IN, FR)")
+    parser.add_argument("-c", "--category", help="Limit scan to specific comma-separated categories (e.g. auth,social)")
+    parser.add_argument("-m", "--module", help="Limit scan to specific comma-separated modules (e.g. microsoft,facebook)")
+    parser.add_argument("-l", "--list", action="store_true", help="List all available categories and modules")
+    parser.add_argument("--all", action="store_true", help="Show all results including not registered and errors")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Display URLs and diagnostic reasons")
+    parser.add_argument("-t", "--timeout", type=float, default=15.0, help="Per-module request timeout in seconds")
+    parser.add_argument("-C", "--concurrency", type=int, default=15, help="Maximum concurrent requests")
+    parser.add_argument("--allow-loud", action="store_true", help="Allow modules that may trigger SMS/notifications")
+    parser.add_argument("-f", "--format", choices=["json", "csv"], default="json", help="Export format (json/csv)")
+    parser.add_argument("-o", "--output", help="Save scan results to file")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+
+    if args.list:
+        list_modules()
+        return
+
+    if not args.phone:
+        print_banner()
+        parser.print_help()
+        print(f"\n{Fore.RED}[!] Error: Please provide a target phone number using -p / --phone.{Style.RESET_ALL}")
+        sys.exit(1)
+
+    print_banner()
+
+    # Step 1: Parse and validate phone number
+    phone_info = parse_phone_number(args.phone, args.region)
+    print(f"\n{Fore.CYAN} Checking phone: {phone_info.e164}{Style.RESET_ALL}")
+
+    if not phone_info.is_valid:
+        print(f"{Fore.YELLOW}[!] Warning: '{args.phone}' is not a standard allocated number according to E.164.{Style.RESET_ALL}")
+        print(f"{Fore.YELLOW}[*] Proceeding with best-effort scan anyway...{Style.RESET_ALL}\n")
+
+    # Step 2: Build scan configuration
+    configs = ScanConfig(
+        allow_loud=args.allow_loud,
+        show_all=args.all,
+        verbose=args.verbose,
+        timeout=args.timeout,
+        concurrency=args.concurrency,
+    )
+
+    # Step 3: Run platform scan
+    results = run_scan(
+        phone_info,
+        configs,
+        category_filter=args.category,
+        module_filter=args.module,
+    )
+
+    # Summary count
+    taken_count = sum(1 for r in results if r.is_found())
+    print(f"\n{Fore.CYAN}== SUMMARY =={Style.RESET_ALL}")
+    print(f"Total Sites Scanned: {len(results)}")
+    print(f"Registered / Found:  {Fore.GREEN}{taken_count}{Style.RESET_ALL}")
+
+    # Step 4: Export if requested
+    if args.output:
+        export_results(results, args.output, args.format)
+
+
+if __name__ == "__main__":
+    main()

phonsint-0.1.0/phonsint/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+Core modules for phonsint
+"""

phonsint-0.1.0/phonsint/core/helpers.py

@@ -0,0 +1,74 @@
+import importlib.util
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Callable, Dict, List, Optional, cast
+
+# List of modules that could potentially alert the target via SMS or phone call
+LOUD_MODULES: List[str] = []
+
+
+@dataclass(frozen=True)
+class ScanConfig:
+    allow_loud: bool = False
+    show_all: bool = False
+    verbose: bool = False
+    timeout: Optional[float] = None
+    concurrency: int = 15
+
+
+def is_loud(site_name: str) -> bool:
+    return site_name.lower() in LOUD_MODULES
+
+
+def get_site_name(module: ModuleType) -> str:
+    name = module.__name__.split(".")[-1].replace("_", " ").title()
+    return name
+
+
+def find_category(module: ModuleType) -> str:
+    parts = module.__name__.split(".")
+    if len(parts) >= 3 and parts[-3] == "modules":
+        return parts[-2].capitalize()
+    return "General"
+
+
+def load_categories() -> Dict[str, Path]:
+    root = Path(__file__).resolve().parent.parent / "modules"
+    categories: Dict[str, Path] = {}
+    if not root.exists():
+        return categories
+
+    for subfolder in root.iterdir():
+        if subfolder.is_dir() and not subfolder.name.startswith("__"):
+            categories[subfolder.name] = subfolder.resolve()
+
+    return categories
+
+
+def load_modules(category_path: Path) -> List[ModuleType]:
+    modules = []
+    for file in category_path.glob("*.py"):
+        if file.name.startswith("__"):
+            continue
+        spec = importlib.util.spec_from_file_location(file.stem, str(file))
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+            modules.append(module)
+        except Exception:
+            continue
+    return modules
+
+
+def get_scan_func(module: ModuleType) -> Optional[Callable[..., Any]]:
+    for attr_name in dir(module):
+        if not attr_name.startswith("validate_"):
+            continue
+        f = getattr(module, attr_name)
+        if inspect.isfunction(f) or inspect.iscoroutinefunction(f):
+            return cast(Callable[..., Any], f)
+    return None

phonsint-0.1.0/phonsint/core/impersonate.py

@@ -0,0 +1,97 @@
+import asyncio
+import threading
+from typing import Literal, Optional, cast
+from curl_cffi import requests as cffi
+
+DEFAULT_IMPERSONATE = "chrome"
+DEFAULT_TIMEOUT = 15.0
+
+_sessions: dict[tuple, cffi.Session] = {}
+_key_locks: dict[tuple, threading.Lock] = {}
+_warmed: set[tuple] = set()
+_lock = threading.Lock()
+_global_timeout: Optional[float] = None
+_global_proxy: Optional[str] = None
+
+
+def set_global_timeout(val: Optional[float]) -> None:
+    global _global_timeout
+    _global_timeout = val
+
+
+def get_global_timeout() -> float:
+    return _global_timeout if _global_timeout is not None else DEFAULT_TIMEOUT
+
+
+def set_global_proxy(val: Optional[str]) -> None:
+    global _global_proxy
+    _global_proxy = val
+
+
+def get_global_proxy() -> Optional[str]:
+    return _global_proxy
+
+
+def _get_warm_session(
+    impersonate: str,
+    proxy: Optional[str],
+    warmup_url: Optional[str] = None,
+) -> cffi.Session:
+    key = (impersonate, proxy)
+    with _lock:
+        session = _sessions.get(key)
+        if session is None:
+            session = cffi.Session(
+                impersonate=impersonate,  # type: ignore[arg-type]
+                proxies={"http": proxy, "https": proxy} if proxy else None,
+            )
+            _sessions[key] = session
+            _key_locks[key] = threading.Lock()
+
+        key_lock = _key_locks.get(key)
+        if key_lock is None:
+            key_lock = threading.Lock()
+            _key_locks[key] = key_lock
+
+    if warmup_url and key not in _warmed:
+        with key_lock:
+            if key not in _warmed:
+                try:
+                    session.get(warmup_url, timeout=get_global_timeout())
+                except Exception:
+                    pass
+                _warmed.add(key)
+
+    return session
+
+
+def impersonate_request(
+    url: str,
+    method: Literal["GET", "POST"] = "GET",
+    warmup_url: Optional[str] = None,
+    impersonate: str = DEFAULT_IMPERSONATE,
+    **kwargs,
+) -> cffi.Response:
+    """Issue a request through a cookie-persistent browser-impersonating curl_cffi session."""
+    session = _get_warm_session(impersonate, get_global_proxy(), warmup_url)
+    kwargs.setdefault("timeout", get_global_timeout())
+    kwargs.setdefault("allow_redirects", False)
+    return cast(cffi.Response, session.request(method, url, **kwargs))
+
+
+async def impersonate_request_async(
+    url: str,
+    method: Literal["GET", "POST"] = "GET",
+    warmup_url: Optional[str] = None,
+    impersonate: str = DEFAULT_IMPERSONATE,
+    **kwargs,
+) -> cffi.Response:
+    """Async wrapper around impersonate_request."""
+    return await asyncio.to_thread(
+        impersonate_request,
+        url,
+        method=method,
+        warmup_url=warmup_url,
+        impersonate=impersonate,
+        **kwargs,
+    )