ja3-client 1.2.5__py3-none-any.whl

ja3_client-1.2.5.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: ja3-client
+Version: 1.2.5
+Summary: Python binding for the ja3-client TLS-impersonation shared library
+Author: smallerqiu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/smallerqiu/ja3-client
+Project-URL: Repository, https://github.com/smallerqiu/ja3-client
+Project-URL: Issues, https://github.com/smallerqiu/ja3-client/issues
+Project-URL: Documentation, https://github.com/smallerqiu/ja3-client/blob/master/cffi/README.md
+Keywords: ja3,ja4,tls,impersonate,fingerprint,ffi,ctypes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ja3-client (Python)
+
+Browser TLS/H2/H3 fingerprint impersonation from Python, through a `ctypes` binding to
+the Go shared library. Pure standard library - no build step, no dependencies. The ABI
+contract (payload keys, response envelope, error codes) is in
+[cffi/README.md](../README.md); this file covers installing the binary the binding needs.
+
+```python
+from ja3_client import Ja3
+
+ja3 = Ja3()
+resp = ja3.request("https://tls.browserleaks.com/json", impersonate="chrome_153")
+print(resp.json()["ja3n_hash"])
+
+with ja3.session(impersonate="chrome_133") as session:
+    session.get("https://example.com/")            # same pool + cookie jar
+```
+
+## Where the library comes from
+
+`pip install ja3-client` installs binding code only. A wheel cannot run code at install
+time, so the native library is fetched the first time `Ja3()` is constructed: the
+resolver downloads `ja3-client-<version>-<os>-<arch>.zip` from this repository's GitHub
+Release for the installed version, checks it against the release's `SHA256SUMS.txt`, and
+unpacks the library into a cache shared with the Node and C# bindings:
+
+```
+~/.cache/ja3-client/<version>/<os>-<arch>/    (macOS: ~/Library/Caches, Windows: %LOCALAPPDATA%)
+```
+
+To fetch it explicitly - before a container build, or on a machine that will later be
+offline:
+
+```sh
+ja3-client ensure          # or: python -m ja3_client_binaries ensure
+ja3-client print-url       # the archive this machine wants
+ja3-client status          # version, slug, cache dir, what is present
+```
+
+At runtime the binding looks for, in order: the `library_path` you pass to `Ja3()`,
+`JA3_CLIENT_LIB`, a library beside it or under `cffi/build`, any version in the shared
+cache, and only then a download.
+
+## Knobs
+
+| variable | effect |
+| --- | --- |
+| `JA3_CLIENT_LIB` | use this exact file; never search, never download |
+| `JA3_CLIENT_CACHE_DIR` | move the cache (also how you point CI at a mirror) |
+| `JA3_CLIENT_VERSION` | library version to fetch, overriding the package version |
+| `JA3_CLIENT_BASE_URL` | download root, for a mirror or an offline test server |
+| `JA3_CLIENT_REPO` | `owner/repo` if you build the library from a fork |
+| `JA3_CLIENT_OFFLINE=1` | never touch the network; fail with the manual recipe |
+
+## No network, no GitHub
+
+Build it and pin it, or unzip a release archive and point `JA3_CLIENT_LIB` at the file
+inside - every archive carries `smoke.py`, which proves the download offline:
+
+```sh
+git clone https://github.com/smallerqiu/ja3-client && cd ja3-client/cffi && make host
+export JA3_CLIENT_LIB="$PWD/build/darwin/ja3_client_arm64.dylib"   # linux: libja3_client_amd64.so
+```
+
+Linux archives are built against glibc (Debian bookworm); on musl (Alpine) build the
+library yourself.

ja3_client-1.2.5.dist-info/RECORD

@@ -0,0 +1,8 @@
+ja3_client.py,sha256=8MLW1hyCUSdca13RgP2ymNMwVLXJMA_nN-WXjyxCBWw,17436
+ja3_client_binaries.py,sha256=38YLaTAiiIB3mKeUTOh4fjdyBJWpOYsvOMyFnIu1aL4,15935
+ja3_client-1.2.5.dist-info/licenses/LICENSE,sha256=DhGbA1FlqMafTzs5mW0vJFeMrGRSF_z7pUiwCw4rHNg,1067
+ja3_client-1.2.5.dist-info/METADATA,sha256=DeAMCje837iNG2DNEM-Qu_ivJysgMNz-FHruG_jdhXI,3726
+ja3_client-1.2.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ja3_client-1.2.5.dist-info/entry_points.txt,sha256=QEmIATNcARQPCiOlQv5Hm81XbitAR0d2rfuqXyRqVa4,56
+ja3_client-1.2.5.dist-info/top_level.txt,sha256=85v4t8RM2ZXcqKU4XjfrvTveEyjE_v1cOp6DwV4h_Ro,31
+ja3_client-1.2.5.dist-info/RECORD,,

ja3_client-1.2.5.dist-info/WHEEL

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

ja3_client-1.2.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ja3-client = ja3_client_binaries:main

ja3_client-1.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 smallerqiu
+
+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.

ja3_client-1.2.5.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+ja3_client
+ja3_client_binaries

ja3_client.py

@@ -0,0 +1,526 @@
+"""Python bindings for the ja3-client shared library (``libja3-client``).
+
+Pure standard library: ``ctypes`` + ``json`` + ``base64``. No build step, no
+third-party packages.
+
+    from ja3_client import Ja3
+
+    ja3 = Ja3()                       # finds and loads the library
+    print(ja3.version())
+    resp = ja3.request("https://tls.browserleaks.com/json", impersonate="chrome_133")
+    print(resp.status_code, resp.json()["ja3n_hash"])
+
+    with ja3.session(impersonate="chrome_133") as session:
+        session.get("https://example.com/")
+        session.get("https://example.com/about")   # same connection pool + cookies
+
+Every call crosses the ABI as one JSON string, so the payload keys and the response
+keys are documented in ``cffi/README.md`` (the ``snake_case`` contract). Unknown keys
+come back in ``Response.warnings`` instead of being dropped.
+"""
+
+from __future__ import annotations
+
+import base64
+import ctypes
+import json
+import os
+import platform
+from typing import Any, Iterable, Iterator, Mapping
+
+__all__ = [
+    "Ja3",
+    "Ja3Error",
+    "Response",
+    "Session",
+    "ABI_VERSION",
+    "ERROR_CODES",
+]
+
+ABI_VERSION = 2
+
+#: ``error_code`` -> name. Mirrors the Go constants in cffi/ffi.go.
+ERROR_CODES = {
+    0: "OK",
+    1: "NIL_ARGUMENT",
+    2: "BAD_JSON",
+    3: "SESSION_INIT",
+    4: "INVALID_HANDLE",
+    5: "REQUEST",
+    6: "READ_BODY",
+    7: "MARSHAL",
+    8: "PANIC",
+}
+
+def _default_library_names() -> Iterator[str]:
+    """Candidate file names for the current platform, most specific first."""
+    system = platform.system()
+    machine = platform.machine().lower()
+
+    arch = {
+        "amd64": "amd64",
+        "x86_64": "amd64",
+        "arm64": "arm64",
+        "aarch64": "arm64",
+        "i386": "386",
+        "i686": "386",
+    }.get(machine, machine)
+
+    if system == "Darwin":
+        yield f"ja3_client_{arch}.dylib"
+        yield "libja3-client.dylib"
+    elif system == "Windows":
+        yield f"ja3_client_{arch}.dll"
+        yield "ja3-client.dll"
+    else:
+        yield f"libja3_client_{arch}.so"
+
+        if machine.startswith("arm"):
+            # 32-bit ARM reports armv6l/armv7l; the release names them armv7/arm.
+            yield "libja3_client_armv7.so"
+            yield "libja3_client_arm.so"
+
+        yield "libja3-client.so"
+
+
+#: The installer module, or None when it is not installed. Undefined = not tried yet;
+#: release archives ship ja3_client.py alone, so its absence is normal, not an error.
+_installer: Any = None
+_installer_tried = False
+
+
+def _through_installer() -> str | None:
+    """Reuse the shared cache, then fetch, through ja3_client_binaries if installed.
+
+    A failed fetch raises with the installer's own three-line recipe: when the problem
+    is a 404 on a release asset, "I looked at these twelve paths" is not the message
+    that helps.
+    """
+    global _installer, _installer_tried
+
+    if not _installer_tried:
+        _installer_tried = True
+
+        try:
+            import ja3_client_binaries as module
+
+            _installer = module
+        except Exception:
+            _installer = None
+
+    if _installer is None:
+        return None
+
+    cached = _installer.find_cached_library(list(_default_library_names()))
+
+    if cached:
+        return cached
+
+    try:
+        return _installer.ensure_library()
+    except Exception as err:
+        raise Ja3Error(str(err), error_code=1) from err
+
+
+#: Options the library only reads when it builds the client. Re-sending them on a
+#: session request would be ignored, so the binding drops them there.
+_CLIENT_ONLY_KEYS = (
+    "impersonate", "ja3", "akamai", "client_data", "proxy", "source_ip", "timeout",
+    "force_http1", "with_http3", "random_extension_order", "with_debug",
+    "not_follow_redirects",
+)
+
+
+class Ja3Error(RuntimeError):
+    """Raised when the library reports a non-zero ``error_code``."""
+
+    def __init__(self, message: str, error_code: int, payload: Mapping[str, Any] | None = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.name = ERROR_CODES.get(error_code, f"UNKNOWN_{error_code}")
+        self.payload = dict(payload or {})
+
+
+class Response:
+    """One successful library call, decoded from the JSON envelope."""
+
+    __slots__ = ("status_code", "protocol", "headers", "body", "body_size", "set_cookies",
+                 "warnings", "session", "raw")
+
+    def __init__(self, payload: Mapping[str, Any]):
+        self.raw = dict(payload)
+        self.status_code: int = payload.get("status_code", 0)
+        self.protocol: str = payload.get("protocol", "")
+        self.headers: dict[str, list[str]] = payload.get("headers", {})
+        self.set_cookies: list[str] = payload.get("set_cookies", [])
+        self.warnings: list[str] = payload.get("warnings", [])
+        self.session: int = payload.get("session", 0)
+        self.body_size: int = payload.get("body_size", 0)
+
+        if payload.get("body_base64"):
+            self.body: bytes = base64.b64decode(payload["body_base64"])
+        else:
+            self.body = payload.get("body", "").encode("utf-8")
+
+    # -- header access -------------------------------------------------------
+
+    def header(self, name: str, default: str | None = None) -> str | None:
+        """First value of ``name``, case-insensitive."""
+        wanted = name.lower()
+
+        for key, values in self.headers.items():
+            if key.lower() == wanted:
+                return values[0] if values else default
+
+        return default
+
+    # -- body access ---------------------------------------------------------
+
+    @property
+    def text(self) -> str:
+        return self.body.decode("utf-8", errors="replace")
+
+    @property
+    def content(self) -> bytes:
+        return self.body
+
+    def json(self) -> Any:
+        return json.loads(self.text)
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status_code < 400
+
+    def raise_for_status(self) -> "Response":
+        if not self.ok:
+            raise Ja3Error(f"HTTP {self.status_code}", error_code=5, payload=self.raw)
+
+        return self
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"<Response {self.status_code} {self.protocol} {self.body_size}B>"
+
+
+class Session:
+    """A handle to a persistent client: connection pool + cookie jar reused."""
+
+    def __init__(self, ja3: "Ja3", handle: int, options: Mapping[str, Any]):
+        self._ja3 = ja3
+        self._handle = handle
+        self._options = dict(options)
+        self._closed = False
+
+    @property
+    def handle(self) -> int:
+        return self._handle
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def request(self, url: str, *, method: str = "GET",
+                headers: Mapping[str, Any] | None = None,
+                body: Any = None, **options: Any) -> Response:
+        if self._closed:
+            raise Ja3Error("session is closed", error_code=4)
+
+        payload = _build_payload(url, method, headers, body, options)
+        # Client-level options were fixed at ja3_session_new; sending them again
+        # would silently do nothing, so keep only the per-call fields.
+        for client_key in _CLIENT_ONLY_KEYS:
+            payload.pop(client_key, None)
+
+        return self._ja3._session_request(self._handle, payload)
+
+    def get(self, url: str, **options: Any) -> Response:
+        return self.request(url, method="GET", **options)
+
+    def post(self, url: str, body: Any = None, **options: Any) -> Response:
+        return self.request(url, method="POST", body=body, **options)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+
+        self._ja3._session_close(self._handle)
+        self._closed = True
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:  # pragma: no cover - best effort
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+class Ja3:
+    """Loaded ``libja3-client`` with a small requests-shaped surface."""
+
+    def __init__(self, library_path: str | os.PathLike[str] | None = None,
+                 search_paths: Iterable[str] = (), check_abi: bool = True):
+        self.path = self._locate(library_path, search_paths)
+        self._lib = self._load(self.path)
+
+        if check_abi:
+            envelope = self._call("ja3_version", None)
+            reported = envelope.get("abi")
+            if reported is not None and reported != ABI_VERSION:
+                raise Ja3Error(
+                    f"{self.path} speaks ABI {reported}, this binding expects {ABI_VERSION}",
+                    error_code=reported or 7,
+                )
+
+            self._version = envelope.get("version", "unknown")
+
+    # -- loading -------------------------------------------------------------
+
+    @staticmethod
+    def _locate(library_path: str | os.PathLike[str] | None,
+                search_paths: Iterable[str]) -> str:
+        env_path = os.environ.get("JA3_CLIENT_LIB")
+        candidates: list[str] = []
+
+        for explicit in (library_path, env_path):
+            if explicit:
+                candidates.append(os.fspath(explicit))
+
+        # JA3_CLIENT_LIB means "this file and nothing else" (cffi/PACKAGING.md), so a
+        # path that is not there has to stop here: falling through to whatever else is on
+        # disk turns a typo in CI into a fingerprint that quietly comes from another
+        # version, and that is the worst kind of bug this library can have.
+        if env_path and not os.path.isfile(env_path):
+            raise Ja3Error(
+                f"JA3_CLIENT_LIB points at {env_path}, which is not a file", error_code=1
+            )
+
+        here = os.path.dirname(os.path.abspath(__file__))
+        root = os.path.dirname(os.path.dirname(here))  # bindings/python -> cffi
+        build_dirs = [
+            os.path.join(root, "build"),
+            os.path.join(root, "build", "release"),
+            os.path.join(root, "build", _sysname()),
+            os.path.join(root, "dist"),
+            here,
+            os.getcwd(),
+            os.path.join(os.getcwd(), "build"),
+        ]
+        build_dirs.extend(os.path.abspath(p) for p in search_paths)
+
+        for directory in build_dirs:
+            for name in _default_library_names():
+                candidates.append(os.path.join(directory, name))
+
+        seen: set[str] = set()
+        tried: list[str] = []
+
+        for candidate in candidates:
+            if candidate in seen:
+                continue
+
+            seen.add(candidate)
+            tried.append(candidate)
+
+            if os.path.isfile(candidate):
+                return candidate
+
+        # Nothing on disk. Ask the installer module, which owns the shared cache
+        # (~/.cache/ja3-client/<version>/<os>-<arch>/) that the npm and NuGet packages
+        # fill, and can fetch this version's archive. The import is lazy and guarded:
+        # the release archives ship ja3_client.py alone, and there the module really is
+        # absent, so the error below is the right answer. An explicit JA3_CLIENT_LIB that
+        # does not exist must not fall through to some other library (cffi/PACKAGING.md),
+        # which is why this whole branch is skipped when one was set.
+        if not env_path:
+            found = _through_installer()
+
+            if found:
+                return found
+
+        raise Ja3Error(
+            "libja3-client not found. Build it with `make` in cffi/, then point "
+            "JA3_CLIENT_LIB at the file. Looked at:\n  " + "\n  ".join(tried[:12]),
+            error_code=1,
+        )
+
+    @staticmethod
+    def _load(path: str) -> ctypes.CDLL:
+        lib = ctypes.CDLL(path)
+
+        cstr = ctypes.c_char_p
+        u64 = ctypes.c_ulonglong
+        ptr = ctypes.c_void_p
+
+        lib.ja3_version.argtypes = []
+        lib.ja3_request.argtypes = [cstr]
+        lib.ja3_session_new.argtypes = [cstr]
+        lib.ja3_session_request.argtypes = [u64, cstr]
+        lib.ja3_session_close.argtypes = [u64]
+        lib.ja3_free.argtypes = [ptr]
+
+        # Every JSON-returning export gives back malloc'd memory the caller owns.
+        # c_void_p (not c_char_p) keeps the pointer so ja3_free can release it.
+        for name in ("ja3_version", "ja3_request", "ja3_session_new",
+                     "ja3_session_request", "ja3_session_close"):
+            getattr(lib, name).restype = ptr
+
+        lib.ja3_free.restype = None
+
+        return lib
+
+    # -- calling -------------------------------------------------------------
+
+    def _call(self, export: str, payload: Mapping[str, Any] | None,
+              *extra: Any) -> dict[str, Any]:
+        args: list[Any] = list(extra)
+
+        if payload is not None:
+            args.append(json.dumps(payload, ensure_ascii=False).encode("utf-8"))
+
+        raw = getattr(self._lib, export)(*args)
+
+        if not raw:
+            raise Ja3Error(f"{export} returned a null pointer", error_code=7)
+
+        try:
+            text = ctypes.string_at(raw).decode("utf-8")
+        finally:
+            self._lib.ja3_free(raw)
+
+        envelope = json.loads(text)
+
+        if envelope.get("error_code", 0) not in (0,):
+            raise Ja3Error(envelope.get("error") or ERROR_CODES.get(envelope["error_code"], "error"),
+                           error_code=envelope["error_code"], payload=envelope)
+
+        return envelope
+
+    # -- public API ----------------------------------------------------------
+
+    def _session_request(self, handle: int, payload: Mapping[str, Any]) -> Response:
+        envelope = self._call("ja3_session_request", payload, ctypes.c_ulonglong(handle))
+
+        return Response(envelope)
+
+    def _session_close(self, handle: int) -> None:
+        self._call("ja3_session_close", None, ctypes.c_ulonglong(handle))
+
+    def version(self) -> str:
+        return getattr(self, "_version", "unknown")
+
+    def request(self, url: str, *, method: str = "GET",
+                 headers: Mapping[str, Any] | None = None,
+                 body: Any = None, **options: Any) -> Response:
+        """One-shot request: builds a client, uses it once, drops idle connections.
+
+        Keyword arguments map onto the payload fields in cffi/README.md, e.g.
+        ``impersonate="chrome_133"``, ``proxy="http://127.0.0.1:7890"``,
+        ``with_http3=False``, ``timeout=20``.
+        """
+        payload = _build_payload(url, method, headers, body, options)
+
+        return Response(self._call("ja3_request", payload))
+
+    def get(self, url: str, **options: Any) -> Response:
+        return self.request(url, method="GET", **options)
+
+    def post(self, url: str, body: Any = None, **options: Any) -> Response:
+        return self.request(url, method="POST", body=body, **options)
+
+    def session(self, **options: Any) -> Session:
+        """Open a persistent client and return its handle wrapper.
+
+        Call ``session.close()`` (or use it as a context manager) - the library
+        keeps the connection pool and cookie jar alive until then.
+        """
+        payload = {k: v for k, v in _drop_none(options).items()}
+        envelope = self._call("ja3_session_new", payload)
+
+        return Session(self, envelope["session"], payload)
+
+    def close(self) -> None:
+        """Nothing to release on the Python side; kept for symmetry."""
+        return None
+
+
+def _sysname() -> str:
+    return {"Darwin": "darwin", "Windows": "windows", "Linux": "linux"}[platform.system()]
+
+
+def _drop_none(options: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in options.items() if value is not None}
+
+
+def _encode_body(body: Any) -> dict[str, str]:
+    if body is None:
+        return {}
+
+    if isinstance(body, bytes):
+        return {"body_base64": base64.b64encode(body).decode("ascii")}
+
+    if isinstance(body, str):
+        try:
+            body.encode("utf-8")
+        except UnicodeEncodeError:  # pragma: no cover - lone surrogates
+            return {"body_base64": base64.b64encode(body.encode("utf-8", "surrogatepass")).decode("ascii")}
+
+        return {"body": body}
+
+    if isinstance(body, bool):
+        return {"body": "true" if body else "false"}
+
+    if isinstance(body, (int, float)):
+        return {"body": str(body)}
+
+    return {"body": json.dumps(body, ensure_ascii=False)}
+
+
+def _build_payload(url: str, method: str, headers: Mapping[str, Any] | None,
+                   body: Any, options: Mapping[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {"url": url, "method": method.upper()}
+
+    if headers is not None:
+        payload["headers"] = dict(headers)
+
+    payload.update(_encode_body(body))
+    payload.update(_drop_none(options))
+
+    return payload
+
+
+_default: Ja3 | None = None
+
+
+def _lazy_default() -> Ja3:
+    global _default
+
+    if _default is None:
+        _default = Ja3()
+
+    return _default
+
+
+def request(url: str, **options: Any) -> Response:
+    """Module-level shortcut using a lazily loaded, process-wide library handle."""
+    return _lazy_default().request(url, **options)
+
+
+def get(url: str, **options: Any) -> Response:
+    return _lazy_default().get(url, **options)
+
+
+def post(url: str, body: Any = None, **options: Any) -> Response:
+    return _lazy_default().post(url, body=body, **options)
+
+
+def session(**options: Any) -> Session:
+    return _lazy_default().session(**options)
+
+
+def version() -> str:
+    return _lazy_default().version()
+

ja3_client_binaries.py

@@ -0,0 +1,508 @@
+"""Install-time resolver for the ja3-client native library.
+
+The PyPI distribution of ``ja3-client`` ships this module next to ``ja3_client.py``.
+The binding code is portable; the Go/cgo build is not, so the library is downloaded
+from the GitHub Release for the matching version and cached in a directory the Node
+and C# bindings share.
+
+    from ja3_client import Ja3          # fetches on first use
+    python -m ja3_client_binaries ensure   # or fetch it explicitly
+
+cffi/PACKAGING.md owns the contract (asset names, SHA256SUMS.txt, cache layout, the
+``JA3_CLIENT_*`` variables); this module is the Python reading of it. Standard library
+only - a resolver that needs a third-party package to fetch a package defeats its own
+purpose.
+
+A wheel cannot run code at install time, so unlike npm's postinstall this fetches on
+first use. ``python -m ja3_client_binaries fetch`` is there for the people who want the
+bytes on disk before the process starts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import shutil
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import Iterator, Optional
+
+__all__ = [
+    "platform_slug",
+    "library_file_name",
+    "cache_dir",
+    "cache_library_path",
+    "resolve_version",
+    "asset_name",
+    "asset_url",
+    "sums_url",
+    "ensure_library",
+    "FindError",
+    "main",
+]
+
+DEFAULT_REPO = "smallerqiu/ja3-client"
+ABI_VERSION = 2
+TIMEOUT_SECONDS = 60
+
+#: Version of the library this package installs. CI stamps it from the release tag at
+#: build time; a hand-built wheel keeps the last published number so the resolver asks
+#: for an archive that actually exists.
+PACKAGE_VERSION = "1.2.5"
+
+_SUPPORTED_SLUGS = (
+    "darwin-amd64", "darwin-arm64",
+    "linux-amd64", "linux-arm64", "linux-armv7", "linux-386",
+    "windows-amd64", "windows-386",
+)
+
+
+def _flag(name: str) -> bool:
+    """Truthy for the env switches: 1/true/yes, in any case; 0/false/no/off are not."""
+    value = os.environ.get(name)
+
+    if value is None or value == "":
+        return False
+
+    return value.strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+
+    return value if value else None
+
+
+def platform_slug(system: Optional[str] = None, machine: Optional[str] = None) -> str:
+    """The ``<os>-<arch>`` half of a release asset name.
+
+    The arch table matches ``ja3_client._default_library_names`` so the file the
+    binding looks for and the file the resolver downloads are the same file, and it
+    matches package-release.sh, which derives the slug from the build directory plus
+    the architecture in the library name.
+    """
+    system = system or platform.system()
+    machine = (machine or platform.machine() or "").lower()
+
+    arch = {
+        "amd64": "amd64",
+        "x86_64": "amd64",
+        "arm64": "arm64",
+        "aarch64": "arm64",
+        "i386": "386",
+        "i686": "386",
+        "x86": "386",
+    }.get(machine, machine)
+
+    if arch.startswith("arm") and arch not in {"arm64"}:
+        # armv6l/armv7l: the release names the 32-bit build after its file, armv7.
+        arch = "armv7"
+
+    os_name = {"Darwin": "darwin", "Windows": "windows", "Linux": "linux"}.get(system)
+
+    if os_name is None:
+        raise FindError(
+            f"ja3-client: no release archive for system {system!r}; "
+            f"build the library (make -C cffi host) and set JA3_CLIENT_LIB"
+        )
+
+    slug = f"{os_name}-{arch}"
+
+    if slug not in _SUPPORTED_SLUGS:
+        raise FindError(
+            f"ja3-client: no release archive for {slug}; "
+            f"build the library (make -C cffi host) and set JA3_CLIENT_LIB"
+        )
+
+    return slug
+
+
+def library_file_name(slug: str) -> str:
+    """The library file inside ``ja3-client-<version>-<slug>.zip``."""
+    arch = slug.split("-")[1]
+
+    if slug.startswith("darwin"):
+        return f"ja3_client_{arch}.dylib"
+
+    if slug.startswith("windows"):
+        return f"ja3_client_{arch}.dll"
+
+    return f"libja3_client_{arch}.so"
+
+
+def resolve_version() -> str:
+    """Library version to fetch: JA3_CLIENT_VERSION, else this package's version."""
+    return _env("JA3_CLIENT_VERSION") or PACKAGE_VERSION
+
+
+def repo() -> str:
+    return _env("JA3_CLIENT_REPO") or DEFAULT_REPO
+
+
+def tag_for(version: str) -> str:
+    return version if version.startswith("v") else f"v{version}"
+
+
+def base_url() -> str:
+    """Download root. The override exists for mirrors and for the offline installer
+    test (cffi/test-installers.sh serves a local dist/); it replaces everything before
+    ``/<tag>/<asset>``."""
+    return _env("JA3_CLIENT_BASE_URL") or f"https://github.com/{repo()}/releases/download"
+
+
+def asset_name(version: str, slug: str) -> str:
+    return f"ja3-client-{version}-{slug}.zip"
+
+
+def asset_url(version: str, slug: str) -> str:
+    return f"{base_url()}/{tag_for(version)}/{asset_name(version, slug)}"
+
+
+def sums_url(version: str) -> str:
+    return f"{base_url()}/{tag_for(version)}/SHA256SUMS.txt"
+
+
+def cache_dir() -> Path:
+    """Cache root shared by the npm, PyPI and NuGet bindings, so one download serves
+    all three on the same machine."""
+    explicit = _env("JA3_CLIENT_CACHE_DIR")
+
+    if explicit:
+        return Path(explicit)
+
+    xdg = _env("XDG_CACHE_HOME")
+
+    if xdg:
+        return Path(xdg) / "ja3-client"
+
+    home = Path.home()
+    system = platform.system()
+
+    if system == "Windows":
+        return Path(_env("LOCALAPPDATA") or home / "AppData" / "Local") / "ja3-client"
+
+    if system == "Darwin":
+        return home / "Library" / "Caches" / "ja3-client"
+
+    return home / ".cache" / "ja3-client"
+
+
+def cache_library_path(version: str, slug: str) -> Path:
+    return cache_dir() / version / slug / library_file_name(slug)
+
+
+class FindError(RuntimeError):
+    """Nothing on disk and nothing downloadable: the caller gets the manual recipe."""
+
+
+class ChecksumError(FindError):
+    """The archive does not match SHA256SUMS.txt - never unpack it."""
+
+
+def download(url: str, timeout: float = TIMEOUT_SECONDS, attempts: int = 2) -> bytes:
+    """Fetch a URL into bytes.
+
+    urllib follows the 302 that GitHub answers at /releases/download/ for us, and that
+    redirect to a signed host is what makes the bytes tamper-evident in transit, so
+    do not "harden" this by disabling redirects. One retry, because a CDN hiccup should
+    not look like a broken package; an HTTP 4xx is a real answer and is not retried.
+    """
+    last: Optional[BaseException] = None
+
+    for attempt in range(attempts):
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as response:
+                code = getattr(response, "status", 200) or 200
+
+                if code != 200:
+                    raise FindError(f"HTTP {code} for {url}")
+
+                return response.read()
+        except urllib.error.HTTPError as err:
+            if 400 <= err.code < 500:
+                raise FindError(f"HTTP {err.code} for {url}") from err
+
+            last = err
+        except (urllib.error.URLError, TimeoutError, OSError) as err:
+            last = err
+
+        if attempt + 1 < attempts:
+            time.sleep(0.5)
+
+    raise FindError(f"could not download {url}: {last}")
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def expected_sha(sums_text: str, asset: str) -> str:
+    """This archive's line from SHA256SUMS.txt (``<sha>  <name>``).
+
+    Exact name match: linux-arm64 and linux-armv7 are one character apart, and a prefix
+    match would report a checksum failure on a perfectly good download. A sums file
+    without a line for this asset means an incomplete release, which is a different
+    problem from a corrupt download and has to be said differently.
+    """
+    for line in sums_text.splitlines():
+        if not line.strip():
+            continue
+
+        sha, name = line[:64].strip(), line[64:].strip().lstrip("*").strip()
+
+        if name == asset:
+            if len(sha) != 64 or any(c not in "0123456789abcdefABCDEF" for c in sha):
+                raise ChecksumError(f"SHA256SUMS.txt has a malformed hash for {asset}")
+
+            return sha.lower()
+
+    raise ChecksumError(f"SHA256SUMS.txt has no line for {asset} - the release is incomplete")
+
+
+def _extract_member(data: bytes, base_name: str, target: Path) -> None:
+    """Write one member of the archive, by base name, into ``target``.
+
+    Only the base name is ever used, so a member named ``../../.ssh/x`` cannot escape
+    the cache directory even though the bytes came off the network.
+    """
+    with zipfile.ZipFile(BytesIO(data)) as archive:
+        for info in archive.infolist():
+            if info.is_dir() or Path(info.filename).name != base_name:
+                continue
+
+            target.write_bytes(archive.read(info))
+
+            return
+
+    raise ChecksumError(f"the archive has no {base_name} inside it")
+
+
+def find_cached_library(names: Optional[Iterator[str]] = None) -> Optional[str]:
+    """A library already in the cache, newest version first.
+
+    The cache outlives upgrades: picking the oldest directory would run a 1.2.5 binding
+    against a 1.2.3 library and the fingerprint mismatch would be blamed on the profiles.
+    """
+    root = cache_dir()
+
+    if not root.is_dir():
+        return None
+
+    wanted = list(names) if names else list(_default_names())
+
+    for version_dir in sorted((p for p in root.iterdir() if p.is_dir()), reverse=True):
+        for slug_dir in sorted((p for p in version_dir.iterdir() if p.is_dir()), reverse=True):
+            for name in wanted:
+                candidate = slug_dir / name
+
+                if candidate.is_file():
+                    return str(candidate)
+
+    return None
+
+
+def _default_names() -> Iterator[str]:
+    """Library file names this machine could use, matching ja3_client's own list."""
+    slug = platform_slug()
+    arch = slug.split("-")[1]
+
+    yield library_file_name(slug)
+
+    if arch == "armv7":
+        yield "libja3_client_arm.so"
+
+
+def _failure(slug: str, version: str, url: str, reason: str) -> FindError:
+    """The three lines PACKAGING.md fixes as the shape of every fetch failure: what was
+    wanted, where it was looked for, and how to do it by hand."""
+    return FindError(
+        f"ja3-client: could not fetch the native library for {slug} ({tag_for(version)}).\n"
+        f"  tried: {url}\n"
+        "  offline? build it (make -C cffi host), or unzip a release archive and "
+        f"set JA3_CLIENT_LIB=/path/to/lib\n  reason: {reason}"
+    )
+
+
+def ensure_library(version: Optional[str] = None, slug: Optional[str] = None,
+                   log=None) -> str:
+    """Return the absolute path of a usable library, downloading it if needed.
+
+    Raises FindError with the manual recipe when nothing is available; never touches the
+    network when JA3_CLIENT_LIB or JA3_CLIENT_OFFLINE says not to.
+    """
+    explicit = _env("JA3_CLIENT_LIB")
+
+    if explicit:
+        if not os.path.isfile(explicit):
+            raise FindError(f"JA3_CLIENT_LIB points at {explicit}, which is not a file")
+
+        return os.path.abspath(explicit)
+
+    version = version or resolve_version()
+    slug = slug or platform_slug()
+    target = cache_library_path(version, slug)
+
+    if target.is_file():
+        if log:
+            log(f"ja3-client: cached {slug} {version}")
+
+        return str(target)
+
+    url = asset_url(version, slug)
+
+    if _flag("JA3_CLIENT_OFFLINE"):
+        raise _failure(slug, version, url, "JA3_CLIENT_OFFLINE is set")
+
+    asset = asset_name(version, slug)
+
+    # Every network step below reports through _failure(), because a bare
+    # "HTTP 404 for .../SHA256SUMS.txt" is a dead end: the sums file is the one missing
+    # asset that means "this release was never finished", and the user still needs the
+    # recipe. A sums line that does not match the archive stays a ChecksumError, which
+    # is a different problem and says so.
+    def fetch(url: str) -> bytes:
+        try:
+            return download(url)
+        except Exception as err:
+            raise _failure(slug, version, url, str(err)) from err
+
+    sums = fetch(sums_url(version)).decode("utf-8", "replace")
+    want = expected_sha(sums, asset)
+    archive = fetch(url)
+
+    got = sha256_hex(archive)
+
+    if got != want:
+        raise _failure(slug, version, url,
+                       f"sha256 is {got}, SHA256SUMS.txt says {want}")
+
+    name = library_file_name(slug)
+
+    # Extract through a temp directory and one rename: an install killed halfway must
+    # not leave a truncated library that ctypes accepts and then crashes inside.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(dir=str(target.parent), prefix=".tmp-"))
+
+    try:
+        _extract_member(archive, name, staging / name)
+        (staging / "install.json").write_text(
+            json.dumps(
+                {
+                    "version": version,
+                    "asset": asset,
+                    "url": url,
+                    "sha256": want,
+                    "abi": ABI_VERSION,
+                    "installed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                    "installed_by": "pip",
+                },
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+
+        for staged in (name, "install.json"):
+            dest = target.parent / staged
+
+            if dest.exists():
+                dest.unlink()
+
+            shutil.move(str(staging / staged), str(dest))
+
+        # ctypes does not care about the mode, but smoke.py runs the file directly on
+        # some systems and a 0600 library is a confusing thing to debug.
+        target.chmod(0o755)
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+    if log:
+        log(f"ja3-client: {slug} {version} -> {target}")
+
+    return str(target)
+
+
+def status() -> dict:
+    version = resolve_version()
+
+    try:
+        slug = platform_slug()
+        path = str(cache_library_path(version, slug))
+        cached = Path(path).is_file()
+    except FindError as err:
+        slug, path, cached = str(err), "", False
+
+    return {
+        "version": version,
+        "package_version": PACKAGE_VERSION,
+        "slug": slug,
+        "repo": repo(),
+        "base_url": base_url(),
+        "cache_dir": str(cache_dir()),
+        "library_path": path,
+        "cached": cached,
+        "offline": _flag("JA3_CLIENT_OFFLINE"),
+        "explicit_lib": _env("JA3_CLIENT_LIB") or "",
+    }
+
+
+_COMMANDS = ("print-url", "ensure", "fetch", "path", "status")
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    command = argv[0] if argv else "status"
+
+    if command in ("-h", "--help"):
+        print(f"usage: python -m ja3_client_binaries <{'|'.join(_COMMANDS)}>")
+
+        return 0
+
+    try:
+        if command == "print-url":
+            print(asset_url(resolve_version(), platform_slug()))
+
+            return 0
+
+        if command in ("ensure", "fetch"):
+            print(ensure_library(log=lambda line: print(line, file=sys.stderr)))
+
+            return 0
+
+        if command == "path":
+            found = cache_library_path(resolve_version(), platform_slug())
+
+            if not found.is_file():
+                print(f"ja3-client: no cached library at {found}", file=sys.stderr)
+
+                return 1
+
+            print(found)
+
+            return 0
+
+        if command == "status":
+            for key, value in status().items():
+                print(f"{key}={value}")
+
+            return 0
+    except FindError as err:
+        print(err, file=sys.stderr)
+
+        return 1
+
+    print(f"unknown command '{command}' ({'|'.join(_COMMANDS)})", file=sys.stderr)
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())