ja4proxy 0.1.0__py3-none-any.whl

ja4proxy/__init__.py

@@ -0,0 +1,9 @@
+"""ja4proxy: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation."""
+
+__version__ = "0.1.0"
+__author__ = "cipherwire"
+
+from ja4proxy.engine.bridge import NativeEngine
+from ja4proxy.server import ProxyServer
+
+__all__ = ["ProxyServer", "NativeEngine", "__version__"]

ja4proxy/certs.py

@@ -0,0 +1,180 @@
+import datetime
+import ipaddress
+import os
+import ssl
+import threading
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.x509.oid import NameOID
+
+
+def _set_private_file_permissions(path: str) -> None:
+    """Restricts file permissions to 0600 on POSIX platforms."""
+    if os.name != "nt":
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+
+
+class CertificateAuthority:
+    """Manages the local root CA and signs dynamic leaf certificates for HTTPS interception."""
+
+    def __init__(self, cert_dir: str | None = None):
+        if cert_dir:
+            self.cert_dir = cert_dir
+        else:
+            self.cert_dir = os.path.join(os.path.expanduser("~"), ".ja4proxy")
+        os.makedirs(self.cert_dir, exist_ok=True)
+
+        self.ca_cert_path = os.path.join(self.cert_dir, "ca.pem")
+        self.ca_key_path = os.path.join(self.cert_dir, "ca.key")
+
+        self._lock = threading.Lock()
+        self._leaf_cache: dict[str, ssl.SSLContext] = {}
+
+        self._ensure_ca()
+
+    def _ensure_ca(self) -> None:
+        """Loads existing CA certificate/key or generates a fresh 10-year root CA."""
+        if os.path.exists(self.ca_cert_path) and os.path.exists(self.ca_key_path):
+            with open(self.ca_key_path, "rb") as f:
+                self.ca_key = serialization.load_pem_private_key(
+                    f.read(), password=None
+                )
+            with open(self.ca_cert_path, "rb") as f:
+                self.ca_cert = x509.load_pem_x509_certificate(f.read())
+            _set_private_file_permissions(self.ca_key_path)
+            return
+
+        # Generate fresh 2048-bit RSA key for CA
+        self.ca_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        ca_name = x509.Name(
+            [
+                x509.NameAttribute(NameOID.COUNTRY_NAME, "US"),
+                x509.NameAttribute(NameOID.ORGANIZATION_NAME, "ja4proxy Development"),
+                x509.NameAttribute(NameOID.COMMON_NAME, "ja4proxy Root CA"),
+            ]
+        )
+
+        now = datetime.datetime.now(datetime.timezone.utc)
+        self.ca_cert = (
+            x509.CertificateBuilder()
+            .subject_name(ca_name)
+            .issuer_name(ca_name)
+            .public_key(self.ca_key.public_key())
+            .serial_number(x509.random_serial_number())
+            .not_valid_before(now - datetime.timedelta(days=1))
+            .not_valid_after(now + datetime.timedelta(days=3650))
+            .add_extension(
+                x509.BasicConstraints(ca=True, path_length=None), critical=True
+            )
+            .add_extension(
+                x509.KeyUsage(
+                    digital_signature=True,
+                    content_commitment=False,
+                    key_encipherment=False,
+                    data_encipherment=False,
+                    key_agreement=False,
+                    key_cert_sign=True,
+                    crl_sign=True,
+                    encipher_only=False,
+                    decipher_only=False,
+                ),
+                critical=True,
+            )
+            .sign(self.ca_key, hashes.SHA256())
+        )
+
+        with open(self.ca_key_path, "wb") as f:
+            f.write(
+                self.ca_key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.TraditionalOpenSSL,
+                    encryption_algorithm=serialization.NoEncryption(),
+                )
+            )
+        _set_private_file_permissions(self.ca_key_path)
+
+        with open(self.ca_cert_path, "wb") as f:
+            f.write(self.ca_cert.public_bytes(serialization.Encoding.PEM))
+
+    def get_ssl_context_for_host(self, host: str) -> ssl.SSLContext:
+        """
+        Dynamically generates or retrieves a cached SSLContext for the target hostname,
+        signed by this CA with appropriate Subject Alternative Names (SAN).
+        """
+        h = host.strip()
+        if h.startswith("["):
+            end = h.find("]")
+            clean_host = h[1:end] if end != -1 else h
+        elif ":" in h:
+            parts = h.split(":")
+            clean_host = parts[0] if len(parts) == 2 else h
+        else:
+            clean_host = h
+
+        with self._lock:
+            if clean_host in self._leaf_cache:
+                return self._leaf_cache[clean_host]
+
+            leaf_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+            subject_name = x509.Name(
+                [
+                    x509.NameAttribute(NameOID.COMMON_NAME, clean_host),
+                ]
+            )
+
+            try:
+                ip_addr = ipaddress.ip_address(clean_host)
+                san = x509.SubjectAlternativeName([x509.IPAddress(ip_addr)])
+            except ValueError:
+                san = x509.SubjectAlternativeName([x509.DNSName(clean_host)])
+
+            now = datetime.datetime.now(datetime.timezone.utc)
+            leaf_cert = (
+                x509.CertificateBuilder()
+                .subject_name(subject_name)
+                .issuer_name(self.ca_cert.subject)
+                .public_key(leaf_key.public_key())
+                .serial_number(x509.random_serial_number())
+                .not_valid_before(now - datetime.timedelta(days=1))
+                .not_valid_after(now + datetime.timedelta(days=365))
+                .add_extension(
+                    x509.BasicConstraints(ca=False, path_length=None), critical=True
+                )
+                .add_extension(san, critical=False)
+                .sign(self.ca_key, hashes.SHA256())
+            )
+
+            cert_pem = leaf_cert.public_bytes(serialization.Encoding.PEM)
+            key_pem = leaf_key.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.TraditionalOpenSSL,
+                encryption_algorithm=serialization.NoEncryption(),
+            )
+
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+
+            leaf_cert_path = os.path.join(self.cert_dir, f"_leaf_{clean_host}.pem")
+            leaf_key_path = os.path.join(self.cert_dir, f"_leaf_{clean_host}.key")
+            with open(leaf_cert_path, "wb") as f:
+                f.write(cert_pem)
+            with open(leaf_key_path, "wb") as f:
+                f.write(key_pem)
+            _set_private_file_permissions(leaf_key_path)
+
+            try:
+                ctx.load_cert_chain(certfile=leaf_cert_path, keyfile=leaf_key_path)
+            finally:
+                try:
+                    os.remove(leaf_cert_path)
+                    os.remove(leaf_key_path)
+                except OSError:
+                    pass
+
+            self._leaf_cache[clean_host] = ctx
+            return ctx

ja4proxy/cli.py

@@ -0,0 +1,154 @@
+import asyncio
+import logging
+import os
+import shutil
+import sys
+
+import click
+
+from ja4proxy import __version__
+from ja4proxy.certs import CertificateAuthority
+from ja4proxy.engine.bridge import NativeEngine
+from ja4proxy.profiles import SUPPORTED_PROFILES, normalize_profile
+from ja4proxy.server import ProxyServer
+
+
+@click.group()
+@click.version_option(__version__, prog_name="ja4proxy")
+def main() -> None:
+    """ja4proxy: High-performance universal proxy server with browser TLS (JA4) and HTTP/2 impersonation."""
+    pass
+
+
+@main.command()
+@click.option("--host", default="127.0.0.1", help="Binding IP address.")
+@click.option("--port", "-p", default=8888, type=int, help="Port to listen on.")
+@click.option(
+    "--profile",
+    default="chrome_133",
+    help="Default browser profile (e.g. chrome_133, safari_18_0, firefox_133).",
+)
+@click.option(
+    "--upstream-proxy",
+    default=None,
+    help="Default upstream proxy URL (e.g. socks5://user:pass@host:1080).",
+)
+@click.option(
+    "--cert-dir", default=None, help="Directory to store CA and leaf certificates."
+)
+@click.option(
+    "--allow-private-networks",
+    is_flag=True,
+    help="Allow forwarding requests to private and loopback IP ranges.",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Enable verbose debug logging.")
+def start(
+    host: str,
+    port: int,
+    profile: str,
+    upstream_proxy: str | None,
+    cert_dir: str | None,
+    allow_private_networks: bool,
+    verbose: bool,
+) -> None:
+    """Starts the ja4proxy server."""
+    log_level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    )
+
+    prof = normalize_profile(profile)
+    server = ProxyServer(
+        host=host,
+        port=port,
+        default_profile=prof,
+        cert_dir=cert_dir,
+        allow_private_networks=allow_private_networks,
+        upstream_proxy=upstream_proxy,
+    )
+
+    ca_path = server.ca.ca_cert_path
+    click.echo(
+        f"[*] ja4proxy v{__version__} starting on http://{host}:{port}"
+    )
+    click.echo(f"[*] Default Profile: {prof}")
+    click.echo(f"[*] Protocols Supported: HTTP CONNECT, HTTP Gateway, SOCKS5 (Auto-detect)")
+    click.echo(f"[*] CA Certificate: {ca_path}")
+    click.echo(
+        "[*] Ready for HTTP and SOCKS5 clients (Python requests, Node axios, cURL, etc.)"
+    )
+
+    try:
+        asyncio.run(server.serve_forever())
+    except KeyboardInterrupt:
+        click.echo("\n[*] Shutting down ja4proxy...")
+
+
+@main.command(name="profiles")
+def list_profiles() -> None:
+    """Lists all supported browser profiles for TLS and HTTP/2 emulation."""
+    click.echo("Supported Browser Profiles:")
+    for prof in SUPPORTED_PROFILES:
+        click.echo(f"  - {prof}")
+
+
+@main.command(name="ca")
+@click.option(
+    "--export",
+    "-e",
+    "export_path",
+    default=None,
+    help="Export root CA certificate (ca.pem) to specified path.",
+)
+def manage_ca(export_path: str | None) -> None:
+    """Inspects or exports the local Root CA certificate."""
+    ca = CertificateAuthority()
+    click.echo(f"Root CA Certificate: {ca.ca_cert_path}")
+    click.echo(f"Root CA Private Key: {ca.ca_key_path}")
+
+    if export_path:
+        dest = os.path.abspath(export_path)
+        shutil.copyfile(ca.ca_cert_path, dest)
+        click.echo(f"Exported CA to: {dest}")
+
+
+@main.command(name="test")
+@click.option(
+    "--profile",
+    default="chrome_133",
+    help="Browser profile to test against tls.peet.ws.",
+)
+def test_handshake(profile: str) -> None:
+    """Performs a direct live handshake against tls.peet.ws to inspect upstream JA4."""
+    import json
+
+    prof = normalize_profile(profile)
+    click.echo(f"Testing upstream handshake for profile: {prof}...")
+
+    async def _test():
+        engine = NativeEngine.get_instance()
+        res = await engine.request(
+            method="GET",
+            url="https://tls.peet.ws/api/all",
+            profile=prof,
+            timeout_seconds=15,
+        )
+        return res
+
+    try:
+        res = asyncio.run(_test())
+        click.echo(f"Status Code: {res['status']}")
+        click.echo(f"Negotiated Protocol: {res['protocol']}")
+
+        body = json.loads(res["body"].decode("utf-8", errors="replace"))
+        tls_info = body.get("tls", {})
+        click.echo(f"Remote Peer JA4: {tls_info.get('ja4')}")
+        click.echo(f"Remote Peer JA3: {tls_info.get('ja3')}")
+        click.echo(f"HTTP Version: {body.get('http_version')}")
+    except Exception as e:
+        click.echo(f"Error executing test: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ja4proxy/engine/bridge.py

@@ -0,0 +1,192 @@
+import asyncio
+import base64
+import ctypes
+import json
+import threading
+from typing import Any
+
+from ja4proxy.engine.loader import resolve_native_library
+from ja4proxy.profiles import get_default_headers, normalize_profile
+
+
+class EngineError(Exception):
+    """Raised when the native uTLS engine fails to execute a request."""
+
+
+class NativeEngine:
+    """In-process bridge to the Go uTLS / fhttp shared library via ctypes."""
+
+    _instance: "NativeEngine | None" = None
+    _init_lock = threading.Lock()
+
+    def __init__(self, lib_path: str | None = None):
+        path = lib_path or resolve_native_library()
+        self.lib = ctypes.cdll.LoadLibrary(path)
+
+        # Set up C function signatures
+        self.lib.request.argtypes = [ctypes.c_char_p]
+        self.lib.request.restype = ctypes.c_char_p
+
+        self.lib.freeMemory.argtypes = [ctypes.c_char_p]
+        self.lib.freeMemory.restype = None
+
+        self.lib.destroySession.argtypes = [ctypes.c_char_p]
+        self.lib.destroySession.restype = ctypes.c_char_p
+
+    @classmethod
+    def get_instance(cls) -> "NativeEngine":
+        if cls._instance is None:
+            with cls._init_lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def _execute_sync(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Synchronously invokes the C function and frees the Go-allocated memory."""
+        payload_bytes = json.dumps(payload).encode("utf-8")
+        resp_ptr = self.lib.request(payload_bytes)
+
+        if not resp_ptr:
+            raise EngineError("Native engine returned null pointer")
+
+        resp_id = None
+        try:
+            raw_bytes = ctypes.string_at(resp_ptr)
+            decoded = raw_bytes.decode("utf-8", errors="replace")
+            resp_obj = json.loads(decoded)
+            if isinstance(resp_obj, dict):
+                resp_id = resp_obj.get("id")
+            return resp_obj
+        except Exception as e:
+            raise EngineError(f"Failed to parse native engine response: {e}") from e
+        finally:
+            if resp_id:
+                try:
+                    self.lib.freeMemory(resp_id.encode("utf-8"))
+                except Exception:
+                    pass
+
+    async def execute_async(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously executes request in threadpool, releasing Python GIL."""
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._execute_sync, payload)
+
+    def destroy_session_sync(self, session_id: str) -> bool:
+        """Destroys an allocated session in the Go engine to release memory and cookies."""
+        payload = json.dumps({"sessionId": session_id}).encode("utf-8")
+        resp_ptr = self.lib.destroySession(payload)
+        if not resp_ptr:
+            return False
+
+        resp_id = None
+        try:
+            raw_bytes = ctypes.string_at(resp_ptr)
+            resp_obj = json.loads(raw_bytes.decode("utf-8", errors="replace"))
+            if isinstance(resp_obj, dict):
+                resp_id = resp_obj.get("id")
+                return bool(resp_obj.get("success", False))
+            return False
+        except Exception:
+            return False
+        finally:
+            if resp_id:
+                try:
+                    self.lib.freeMemory(resp_id.encode("utf-8"))
+                except Exception:
+                    pass
+
+    async def destroy_session(self, session_id: str) -> bool:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.destroy_session_sync, session_id)
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        body: bytes | None = None,
+        profile: str = "chrome_133",
+        proxy_url: str = "",
+        timeout_seconds: int = 30,
+        follow_redirects: bool = False,
+        insecure_skip_verify: bool = False,
+        session_id: str = "ja4_default",
+    ) -> dict[str, Any]:
+        """
+        Dispatches an HTTP request through the native uTLS engine.
+        Merges canonical browser headers to ensure the target never sees automated client signatures.
+        """
+        prof = normalize_profile(profile)
+        is_byte_req = False
+        encoded_body = ""
+        if body:
+            encoded_body = base64.b64encode(body).decode("utf-8")
+            is_byte_req = True
+
+        # Start with default browser headers for the profile
+        merged_headers: dict[str, str] = get_default_headers(prof)
+
+        # Overlay client headers (case-insensitive merge)
+        if headers:
+            for k, v in headers.items():
+                if v is not None:
+                    merged_headers[k.lower()] = str(v)
+
+        payload = {
+            "sessionId": session_id,
+            "tlsClientIdentifier": prof,
+            "requestMethod": method.upper(),
+            "requestUrl": url,
+            "requestBody": encoded_body,
+            "isByteRequest": is_byte_req,
+            "isByteResponse": True,
+            "headers": merged_headers,
+            "requestCookies": [],
+            "proxyUrl": proxy_url,
+            "timeoutSeconds": timeout_seconds,
+            "followRedirects": follow_redirects,
+            "insecureSkipVerify": insecure_skip_verify,
+            "forceHttp1": False,
+            "withProtocolRacing": False,
+            "disableHttp3": True,
+            "withRandomTLSExtensionOrder": False,
+        }
+
+        raw = await self.execute_async(payload)
+
+        status_code = raw.get("status", 0)
+        raw_headers = raw.get("headers", {})
+        used_protocol = raw.get("usedProtocol", "")
+
+        # Decode response body
+        raw_body = raw.get("body", "")
+        body_bytes = b""
+        if isinstance(raw_body, str) and raw_body:
+            if raw_body.startswith("data:") and "," in raw_body:
+                raw_body = raw_body.split(",", 1)[1]
+            try:
+                body_bytes = base64.b64decode(raw_body)
+            except Exception:
+                body_bytes = raw_body.encode("utf-8")
+
+        # Map native failure (status 0) to 502 Bad Gateway
+        if status_code == 0:
+            status_code = 502
+            error_msg = raw.get("errorMessage") or (
+                body_bytes.decode("utf-8", errors="replace")
+                if body_bytes
+                else "Bad Gateway: upstream connection failed"
+            )
+            body_bytes = (
+                error_msg.encode("utf-8")
+                if isinstance(error_msg, str)
+                else error_msg
+            )
+
+        return {
+            "status": status_code,
+            "headers": raw_headers,
+            "body": body_bytes,
+            "protocol": used_protocol,
+            "target": raw.get("target", url),
+        }

ja4proxy/engine/loader.py

@@ -0,0 +1,162 @@
+import ctypes
+import hashlib
+import os
+import platform
+import sys
+import threading
+import urllib.request
+
+OWNER = "bogdanfinn"
+REPO = "tls-client"
+DEFAULT_VERSION = "1.16.0"
+
+RELEASE_DOWNLOAD_URL = (
+    f"https://github.com/{OWNER}/{REPO}/releases/download/v{DEFAULT_VERSION}/{{asset}}"
+)
+
+ASSET_SHA256: dict[str, str] = {
+    "tls-client-xgo-1.16.0-darwin-amd64.dylib": "9cb5fd24bceb74cedd4372bdbdf013058c650fa6f8df2a1336918d8ee54128d8",
+    "tls-client-xgo-1.16.0-darwin-arm64.dylib": "f3a6f5ffadc4a7f5184d9880380e522fbaf6890c623eae1ac0805071f42f5aaa",
+    "tls-client-xgo-1.16.0-linux-386.so": "5ea81308e53e236dae73b35bd4a09af1201191c32713ea2968b85bbcfe94b616",
+    "tls-client-xgo-1.16.0-linux-amd64.so": "75f19133e3cb9b16ab3d2dfe3376c7590aab2fe6f2294debac661bfd63dca6a3",
+    "tls-client-xgo-1.16.0-linux-arm-5.so": "02cca934f2fc15db658e2d94ed472691224656b696c6531ffec2d0aad2997b2f",
+    "tls-client-xgo-1.16.0-linux-arm-6.so": "5c991eca511de6d0ea04f12100c89a7750696213e246226e4050d88bf7e9136b",
+    "tls-client-xgo-1.16.0-linux-arm-7.so": "ee9125b4580bf3e1515304e6faeb4ce30eb88f47c5158349a14d38b25448c358",
+    "tls-client-xgo-1.16.0-linux-arm64.so": "91f88d35fa64284c811373003d2a26caa3145eaeefd1c0e9576f10724a914332",
+    "tls-client-xgo-1.16.0-windows-386.dll": "f41099111446ec3252166b640156a2213d387511e4e80e849ce8b8a0871be47f",
+    "tls-client-xgo-1.16.0-windows-amd64.dll": "33d9b5a4a1a902bae57494186ddce91af32fb67326d94ea04776447a81c15934",
+}
+
+_loader_lock = threading.Lock()
+
+
+def get_system_platform() -> tuple[str, str]:
+    """Detects system OS and CPU architecture."""
+    system_os = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if system_os == "darwin":
+        return "darwin", ("arm64" if machine == "arm64" else "amd64")
+
+    if system_os in ("windows", "win32", "cygwin"):
+        return "windows", ("amd64" if ctypes.sizeof(ctypes.c_voidp) == 8 else "386")
+
+    sys_os = "linux"
+    if machine in ("aarch64", "arm64"):
+        return sys_os, "arm64"
+    if machine in ("x86_64", "amd64"):
+        return sys_os, "amd64"
+    if machine in ("i386", "i486", "i586", "i686", "x86"):
+        return sys_os, "386"
+    return sys_os, "amd64"
+
+
+def get_asset_filename() -> str:
+    """Builds the asset filename for the current platform."""
+    sys_os, arch = get_system_platform()
+    ext = "dll" if sys_os == "windows" else ("dylib" if sys_os == "darwin" else "so")
+    return f"tls-client-xgo-{DEFAULT_VERSION}-{sys_os}-{arch}.{ext}"
+
+
+def get_cache_directory() -> str:
+    """Returns the persistent directory for storing native binaries."""
+    env_dir = os.getenv("JA4PROXY_CACHE_DIR")
+    if env_dir:
+        os.makedirs(env_dir, exist_ok=True)
+        return env_dir
+
+    if sys.platform == "win32":
+        base = os.getenv("LOCALAPPDATA") or os.path.join(
+            os.path.expanduser("~"), "AppData", "Local"
+        )
+        cache_dir = os.path.join(base, "ja4proxy")
+    else:
+        xdg = os.getenv("XDG_CACHE_HOME") or os.path.join(
+            os.path.expanduser("~"), ".cache"
+        )
+        cache_dir = os.path.join(xdg, "ja4proxy")
+
+    os.makedirs(cache_dir, exist_ok=True)
+    return cache_dir
+
+
+def _compute_sha256(path: str) -> str:
+    hasher = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def resolve_native_library() -> str:
+    """
+    Finds or downloads the native Go shared library.
+    Resolves in order:
+    1. JA4PROXY_LIB_PATH env var
+    2. Local ja4proxy cache directory
+    3. Existing horaa-tls cache directory (fallback reuse)
+    4. Direct download from GitHub releases with SHA-256 verification
+    """
+    with _loader_lock:
+        custom_path = os.getenv("JA4PROXY_LIB_PATH")
+        if custom_path and os.path.exists(custom_path):
+            return custom_path
+
+        asset_name = get_asset_filename()
+        cache_dir = get_cache_directory()
+        target_path = os.path.join(cache_dir, asset_name)
+
+        if os.path.exists(target_path):
+            expected_hash = ASSET_SHA256.get(asset_name)
+            if expected_hash:
+                actual_hash = _compute_sha256(target_path)
+                if actual_hash == expected_hash:
+                    return target_path
+
+        # Check existing horaa-tls cache location
+        if sys.platform == "win32":
+            local_appdata = os.getenv("LOCALAPPDATA") or ""
+            horaa_path = os.path.join(local_appdata, "horaa-tls", asset_name)
+            if os.path.exists(horaa_path):
+                expected_hash = ASSET_SHA256.get(asset_name)
+                if not expected_hash or _compute_sha256(horaa_path) == expected_hash:
+                    return horaa_path
+        else:
+            xdg = os.getenv("XDG_CACHE_HOME") or os.path.join(
+                os.path.expanduser("~"), ".cache"
+            )
+            horaa_path = os.path.join(xdg, "horaa-tls", asset_name)
+            if os.path.exists(horaa_path):
+                expected_hash = ASSET_SHA256.get(asset_name)
+                if not expected_hash or _compute_sha256(horaa_path) == expected_hash:
+                    return horaa_path
+
+        # Download from GitHub release
+        download_url = RELEASE_DOWNLOAD_URL.format(asset=asset_name)
+        temp_path = target_path + ".tmp"
+        try:
+            req = urllib.request.Request(
+                download_url, headers={"User-Agent": "ja4proxy/0.1.0"}
+            )
+            with urllib.request.urlopen(req, timeout=60) as resp, open(
+                temp_path, "wb"
+            ) as out:
+                for chunk in iter(lambda: resp.read(65536), b""):
+                    out.write(chunk)
+
+            expected_hash = ASSET_SHA256.get(asset_name)
+            if expected_hash:
+                actual_hash = _compute_sha256(temp_path)
+                if actual_hash != expected_hash:
+                    raise RuntimeError(
+                        f"SHA-256 mismatch for {asset_name}: expected {expected_hash}, got {actual_hash}"
+                    )
+
+            os.replace(temp_path, target_path)
+            return target_path
+        finally:
+            if os.path.exists(temp_path):
+                try:
+                    os.remove(temp_path)
+                except OSError:
+                    pass