protox-gatekeeper 0.1.1__py3-none-any.whl

protox_gatekeeper/__init__.py

@@ -0,0 +1,3 @@
+from protox_gatekeeper.core import GateKeeper
+
+__all__ = ['GateKeeper']

protox_gatekeeper/core.py

@@ -0,0 +1,92 @@
+import logging
+
+import requests
+
+from protox_gatekeeper.session import make_tor_session
+from protox_gatekeeper.verify import is_tor_exit, get_public_ip
+from protox_gatekeeper.ops import download_file as _download
+from protox_gatekeeper.geo import geo_lookup
+
+logger = logging.getLogger(__name__)
+
+
+class GateKeeper:
+    def __init__(self, socks_port: int = 9150, geo=False, timeout: int = 10):
+        """
+        GateKeeper constructor.
+
+        Args:
+            socks_port (int, optional): The socks port to use. Defaults to 9150.
+            geo (bool, optional): Whether to use geo. Defaults to False.
+            timeout (int, optional): The timeout to wait for a response. Defaults to 10.
+        """
+
+        self._session: requests.Session
+        self.exit_ip: str
+        self.clearnet_ip: str
+
+        # 1) Measure clearnet IP (no proxies)
+        clearnet = requests.Session()
+        self.clearnet_ip = get_public_ip(session=clearnet, timeout=timeout)
+
+        # 2) Create Tor session
+        self._session = make_tor_session(port=socks_port)
+
+        # 3) Verify Tor routing
+        if not is_tor_exit(session=self._session, timeout=timeout):
+            raise RuntimeError('Tor verification failed. Execution aborted.')
+
+        # 4) Measure Tor exit IP
+        self.exit_ip = get_public_ip(session=self._session, timeout=timeout)
+
+        # 5) Log the transition
+        logger.info(f'Tor verified: {self.clearnet_ip} -> {self.exit_ip}')
+
+        # 6) Location data
+        if geo:
+            location = geo_lookup(self.exit_ip)
+            if location:
+                logger.info(f'Tor exit location: {location}')
+            else:
+                logger.info('Tor exit location: Unavailable')
+
+    def __repr__(self) -> str:
+        return f'<GateKeeper: {self.clearnet_ip} -> tor_exit: {self.exit_ip}>'
+
+    def __enter__(self) -> "GateKeeper":
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self._session.close()
+
+    @property
+    def session(self) -> requests.Session:
+        """ Exposes the verified session if needed. """
+        return self._session
+
+    @property
+    def tor_exit(self) -> str:
+        """ Returns the Tor exit IP address. """
+        return self.exit_ip
+
+    def download(self, url: str, target_path: str, timeout: int = 30,
+                 chunk_size: int = 8192):
+        """
+        Attempts to download the given url to the target path.
+
+        Args:
+            url (str): The url to download.
+            target_path (str): The target path.
+            timeout (int, optional): The timeout to wait for a response.
+            chunk_size (int, optional): The chunk size to use for download.
+        """
+        logger.info(
+            f'[Tor {self.tor_exit}] downloading {url} -> {target_path}')
+
+        return _download(
+            session=self._session,
+            url=url,
+            target_path=target_path,
+            timeout=timeout,
+            chunk_size=chunk_size
+        )

protox_gatekeeper/geo.py

@@ -0,0 +1,26 @@
+import logging
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+def geo_lookup(ip: str) -> str | None:
+    try:
+        r = requests.get(
+            url=f'https://ipapi.co/{ip}/json',
+            timeout=10,
+            headers={'User-Agent': 'GateKeeper/0.1.0'}
+        )
+        if r.status_code != 200:
+            return None
+
+        data = r.json()
+        city = data.get('city')
+        country = data.get('country')
+        if city and country:
+            return f'{city}, {country}'
+
+    except Exception as e:
+        logger.info(f'Unable to get geolocation for {ip}: {e}')
+        return None

protox_gatekeeper/ops.py

@@ -0,0 +1,26 @@
+import os
+
+import requests
+
+
+def download_file(
+        session: requests.Session,
+        url: str,
+        target_path: str,
+        timeout: int,
+        chunk_size: int
+) -> None:
+    if not isinstance(session, requests.Session):
+        raise TypeError('A verified requests.Session is required.')
+
+    dir_path = os.path.dirname(target_path)
+    if dir_path:
+        os.makedirs(dir_path, exist_ok=True)
+
+    response = session.get(url, stream=True, timeout=timeout)
+    response.raise_for_status()
+
+    with open(target_path, 'wb') as f:
+        for chunk in response.iter_content(chunk_size=chunk_size):
+            if chunk:
+                f.write(chunk)

protox_gatekeeper/session.py

@@ -0,0 +1,11 @@
+import requests
+
+
+def make_tor_session(port: int) -> requests.Session:
+    socks = f'socks5h://127.0.0.1:{port}'
+    s = requests.Session()
+    s.proxies = {
+        'http': socks,
+        'https': socks,
+    }
+    return s

protox_gatekeeper/verify.py

@@ -0,0 +1,14 @@
+import requests
+
+
+def get_public_ip(session: requests.Session, timeout: int) -> str:
+    r = session.get(url='https://api.ipify.org/', timeout=timeout)
+    r.raise_for_status()
+    return r.text.strip()
+
+
+def is_tor_exit(session: requests.Session, timeout: int) -> bool:
+    r = session.get(url='https://check.torproject.org/api/ip', timeout=timeout)
+    r.raise_for_status()
+    data = r.json()
+    return bool(data.get('IsTor', False))

protox_gatekeeper-0.1.1.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: protox-gatekeeper
+Version: 0.1.1
+Summary: Fail-closed Tor session enforcement for Python HTTP(S) traffic
+Author: Tom Erik Harnes
+License: MIT License
+        
+        Copyright (c) 2026 Tom Erik Harnes
+        
+        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.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pysocks
+Dynamic: license-file
+
+# ProtoX GateKeeper
+
+**ProtoX GateKeeper** is a small, opinionated Python library that enforces
+**fail‑closed Tor routing** for HTTP(S) traffic.
+
+The goal is simple:
+
+> If Tor is not active and verified, **nothing runs**.
+
+GateKeeper is designed to be *fire‑and‑forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
+
+---
+
+## What GateKeeper Is
+
+- A **Tor‑verified HTTP client**
+- A thin wrapper around `requests.Session`
+- Fail‑closed by default (no silent clearnet fallback)
+- Observable (exit IP, optional geo info)
+- Suitable for scripts, tooling, and automation
+
+---
+
+## What GateKeeper Is NOT
+
+- ❌ A Tor controller
+- ❌ A crawler or scanner
+- ❌ An anonymization silver bullet
+- ❌ A replacement for Tor Browser
+
+GateKeeper enforces transport routing only. You are still responsible for *what* you do with it.
+
+---
+
+## Requirements
+
+- A locally running Tor client
+- SOCKS proxy enabled (default: `127.0.0.1:9150`)
+
+On Windows this usually means **Tor Browser** running in the background.
+
+---
+
+## Installation
+
+### From source (development)
+
+```bash
+pip install -e .
+```
+
+(Recommended while developing or testing.)
+
+---
+
+## Basic Usage
+
+```python
+import logging
+from protox_gatekeeper import GateKeeper
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='[%(levelname)s] %(name)s - %(message)s'
+)
+
+gk = GateKeeper(geo=True)
+
+gk.download(
+    "https://httpbin.org/bytes/1024",
+    "downloads/test.bin"
+)
+```
+
+### Example output
+
+```
+[INFO] gatekeeper.core - Tor verified: 89.xxx.xxx.xxx -> 185.xxx.xxx.xxx
+[INFO] gatekeeper.core - Tor exit location: Brandenburg, DE
+[INFO] gatekeeper.core - [Tor 185.xxx.xxx.xxx] downloading https://httpbin.org/bytes/1024 -> downloads/test.bin
+```
+
+This confirms:
+- clearnet IP was measured
+- Tor routing was verified
+- all traffic used the Tor exit shown
+
+---
+
+## API Overview
+
+### `GateKeeper(...)`
+
+```python
+gk = GateKeeper(
+    socks_port=9150,
+    geo=False
+)
+```
+
+**Parameters**:
+- `socks_port` *(int)* – Tor SOCKS port (default: `9150`)
+- `geo` *(bool)* – Enable best‑effort Tor exit geolocation (optional)
+
+Raises `RuntimeError` if Tor routing cannot be verified.
+
+---
+
+### `download(url, target_path)`
+
+Downloads a resource **through the verified Tor session**.
+
+```python
+gk.download(url, target_path)
+```
+
+- `url` – HTTP(S) URL
+- `target_path` – Full local file path (directories created automatically)
+
+---
+
+## Design Principles
+
+- **Fail closed**: no Tor → no execution
+- **Single verification point** (during construction)
+- **No global state**
+- **No logging configuration inside the library**
+- **Session reuse without re‑verification**
+
+Logging is emitted by the library, but **configured by the application**.
+
+---
+
+## Logging
+
+GateKeeper uses standard Python logging:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+The library does **not** call `logging.basicConfig()` internally.
+
+---
+
+## Security Notes
+
+- Tor exit IPs may rotate over time
+- Geo information is best‑effort and may be unavailable (rate‑limits, CAPTCHAs)
+- GateKeeper guarantees routing, not anonymity
+
+---
+
+## License
+
+MIT License
+
+---
+
+## Status
+
+- Version: **v0.1.1**
+- Phase 1 complete
+- API intentionally minimal
+
+Future versions may add optional features such as:
+- circuit rotation
+- ControlPort support
+- higher‑level request helpers
+
+Without breaking the core contract.
+

protox_gatekeeper-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+protox_gatekeeper/__init__.py,sha256=HisDC-NCbMlkrNkrLRdANILoBqw03ssqFp6BTsXm6Us,75
+protox_gatekeeper/core.py,sha256=Z4LEY1WcSbjMDU3OS1rf7kPOTry9NJq5-quzACxPvKg,3062
+protox_gatekeeper/geo.py,sha256=AdjHfZqjP0w5ujHFI_WV7c5XWnDTzqkVL32KeJQojYo,641
+protox_gatekeeper/ops.py,sha256=Kmr8lU8Ohe81URHHNUlUJ0S71aZ1uGgyiztLBPsOUO4,690
+protox_gatekeeper/session.py,sha256=0qGZF44EHr7CP-bSM0awtq4F-5LWiIb4w87mV7Yocfk,235
+protox_gatekeeper/verify.py,sha256=bsHK3f16sRV8cHo30AY82SB1vb_Svu-US7IhghTSQ6E,452
+protox_gatekeeper-0.1.1.dist-info/licenses/LICENSE,sha256=EE75Vy9_csDDBRXBF4uVQWxYu1YpzXTcmaeuVcPOjl4,1093
+protox_gatekeeper-0.1.1.dist-info/METADATA,sha256=g3ib-yUF_vfoi6oD3S6z9BfkIfP9-YylLl7cXnCq1a4,5215
+protox_gatekeeper-0.1.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+protox_gatekeeper-0.1.1.dist-info/top_level.txt,sha256=KOVL4YUpiWQLGjCvx2SmP8VSsA6hPcEvKCd4k6kPl8s,18
+protox_gatekeeper-0.1.1.dist-info/RECORD,,

protox_gatekeeper-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

protox_gatekeeper-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Erik Harnes
+
+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.

protox_gatekeeper-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+protox_gatekeeper