fizzpy 0.5.0__cp315-cp315-win_amd64.whl

fizzpy/__init__.py

@@ -0,0 +1,330 @@
+"""fizzpy — post-quantum TLS 1.3 for Python, built on Facebook's Fizz.
+
+Two ways to use it. Plug Fizz under an HTTP client you already have — mount
+:class:`fizzpy.contrib.requests.FizzAdapter` on a ``requests.Session``, or wrap
+any connected socket with :func:`fizzpy.wrap_socket` — and keep that client's
+cookies, redirects, and pooling while Fizz does the handshake. Or use the small
+built-in client (this module, sync) / :mod:`fizzpy.aio` (async); both drive the
+same C++ core, which runs every connection on a background EventBase thread.
+
+    import fizzpy
+
+    r = fizzpy.get("https://www.cloudflare.com")
+    print(r.status_code, r.headers["content-type"])
+    print(r.tls)  # negotiated TLS 1.3 parameters
+
+Certificate chains are verified against the system trust store and the
+hostname is checked against the certificate's SAN by default.
+"""
+
+from __future__ import annotations
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_2():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'fizzpy.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_2()
+del _delvewheel_patch_1_13_2
+# end delvewheel patch
+
+import threading
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from . import _core
+from ._common import (
+    DEFAULT_ALPN,
+    DEFAULT_GROUPS,
+    DEFAULT_MAX_REDIRECTS,
+    DEFAULT_TIMEOUT_MS,
+    READ_DONE,
+    Extension,
+    Target,
+    TooManyRedirects,
+    default_ca_file,
+    next_redirect,
+    normalize_extensions,
+    parse_url,
+    strip_body_headers,
+    supports_post_quantum,
+    timeout_to_ms,
+)
+from ._core import NamedGroup
+from ._http import Headers, Response, ResponseParser, build_request
+from ._tls import TlsConfig, TlsSocket, wrap_socket
+from ._transport import run_sync
+
+__all__ = [
+    "Client",
+    "Extension",
+    "Headers",
+    "NamedGroup",
+    "Response",
+    "TlsConfig",
+    "TlsParameters",
+    "TlsSocket",
+    "TooManyRedirects",
+    "delete",
+    "get",
+    "head",
+    "post",
+    "put",
+    "request",
+    "supports_post_quantum",
+    "wrap_socket",
+]
+
+# Negotiated parameters are returned from the core as a plain dict; expose the
+# key set as documentation.
+TlsParameters = dict
+
+
+class _Stale(Exception):
+    """Internal: a pooled connection was dead; retry once on a fresh one."""
+
+
+class Client:
+    """A synchronous TLS HTTP client.
+
+    Idle connections are kept in a per-host pool and reused (HTTP/1.1
+    keep-alive). A pooled connection found dead on reuse is transparently
+    replaced for idempotent retries. Call :meth:`close` (or use the client as a
+    context manager) to close pooled connections.
+    """
+
+    def __init__(
+        self,
+        *,
+        verify: bool = True,
+        cafile: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_MS / 1000,
+        alpn: list[str] | None = None,
+        groups: list[_core.NamedGroup] | None = None,
+        extensions: Sequence[tuple[int, bytes]] | None = None,
+        follow_redirects: bool = True,
+        max_redirects: int = DEFAULT_MAX_REDIRECTS,
+    ) -> None:
+        self._verify = verify
+        self._cafile = cafile or default_ca_file()
+        self._timeout_ms = timeout_to_ms(timeout)
+        self._alpn = list(alpn) if alpn is not None else list(DEFAULT_ALPN)
+        self._groups = list(groups) if groups is not None else list(DEFAULT_GROUPS)
+        self._extensions = normalize_extensions(extensions)
+        self._follow_redirects = follow_redirects
+        self._max_redirects = max_redirects
+        self._pool: dict[tuple[str, int], list[_core.TlsConnection]] = {}
+        self._lock = threading.Lock()
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+    ) -> Response:
+        method = method.upper()
+        seen = 0
+        while True:
+            response = self._perform(method, url, headers=headers, body=body)
+            response.url = url
+            nxt = (
+                next_redirect(
+                    method, url, response.status_code, response.headers.get("Location")
+                )
+                if self._follow_redirects
+                else None
+            )
+            if nxt is None:
+                return response
+            if seen >= self._max_redirects:
+                raise TooManyRedirects(
+                    f"exceeded {self._max_redirects} redirects (last: {url})"
+                )
+            new_method, url = nxt
+            if new_method != method:
+                method, body, headers = new_method, None, strip_body_headers(headers)
+            seen += 1
+
+    def _perform(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+    ) -> Response:
+        target = parse_url(url)
+        key = (target.host, target.port)
+        raw = build_request(
+            method, target.path, target.host, dict(headers) if headers else None, body
+        )
+
+        pooled = self._take(key)
+        if pooled is not None:
+            try:
+                return self._exchange(pooled, key, raw, reused=True)
+            except _Stale:
+                pooled.close()  # dead idle connection; fall through to a fresh one
+
+        return self._exchange(self._connect(target), key, raw, reused=False)
+
+    def _connect(self, target: Target) -> _core.TlsConnection:
+        conn = _core.TlsConnection()
+        run_sync(
+            lambda resolve, reject: conn.connect(
+                target.host,
+                target.port,
+                target.host,
+                self._alpn,
+                self._groups,
+                self._verify,
+                self._cafile,
+                self._timeout_ms,
+                self._extensions,
+                resolve,
+                reject,
+            )
+        )
+        return conn
+
+    def _exchange(
+        self,
+        conn: _core.TlsConnection,
+        key: tuple[str, int],
+        raw: bytes,
+        *,
+        reused: bool,
+    ) -> Response:
+        try:
+            run_sync(
+                lambda resolve, reject: conn.write(
+                    self._timeout_ms, raw, resolve, reject
+                )
+            )
+        except Exception as exc:
+            # A reused connection that fails before the request lands was closed
+            # by the server while idle — safe to retry on a fresh one.
+            if reused:
+                raise _Stale from exc
+            raise
+
+        parser = ResponseParser()
+        received = False
+        while not parser.is_complete():
+            try:
+                chunk = run_sync(
+                    lambda resolve, reject: conn.read(self._timeout_ms, resolve, reject)
+                )
+            except Exception as exc:
+                if reused and not received:
+                    raise _Stale from exc
+                raise
+            if chunk == READ_DONE:
+                if reused and not received:
+                    raise _Stale
+                parser.feed_eof()
+                break
+            received = True
+            parser.feed(chunk)
+
+        response = parser.response
+        if response is None:
+            if reused:
+                raise _Stale
+            raise ConnectionError("connection closed before a full response")
+        response.tls = conn.negotiated()
+
+        if self._reusable(parser, response):
+            self._give(key, conn)
+        else:
+            conn.close()
+        return response
+
+    @staticmethod
+    def _reusable(parser: ResponseParser, response: Response) -> bool:
+        if parser.used_close_framing or response.http_version != "HTTP/1.1":
+            return False
+        return "close" not in (response.headers.get("Connection") or "").lower()
+
+    def _take(self, key: tuple[str, int]) -> _core.TlsConnection | None:
+        with self._lock:
+            conns = self._pool.get(key)
+            return conns.pop() if conns else None
+
+    def _give(self, key: tuple[str, int], conn: _core.TlsConnection) -> None:
+        with self._lock:
+            self._pool.setdefault(key, []).append(conn)
+
+    def close(self) -> None:
+        """Close all pooled connections."""
+        with self._lock:
+            pooled = [c for conns in self._pool.values() for c in conns]
+            self._pool.clear()
+        for conn in pooled:
+            conn.close()
+
+    def get(self, url: str, **kwargs: Any) -> Response:
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> Response:
+        return self.request("POST", url, **kwargs)
+
+    def head(self, url: str, **kwargs: Any) -> Response:
+        return self.request("HEAD", url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> Response:
+        return self.request("PUT", url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> Response:
+        return self.request("DELETE", url, **kwargs)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+_CLIENT_KWARGS = frozenset(
+    {
+        "verify",
+        "cafile",
+        "timeout",
+        "alpn",
+        "groups",
+        "extensions",
+        "follow_redirects",
+        "max_redirects",
+    }
+)
+
+
+def request(method: str, url: str, **kwargs: Any) -> Response:
+    """One-shot request with a throwaway :class:`Client`."""
+    client_kwargs = {k: kwargs.pop(k) for k in list(kwargs) if k in _CLIENT_KWARGS}
+    return Client(**client_kwargs).request(method, url, **kwargs)
+
+
+def get(url: str, **kwargs: Any) -> Response:
+    return request("GET", url, **kwargs)
+
+
+def post(url: str, **kwargs: Any) -> Response:
+    return request("POST", url, **kwargs)
+
+
+def head(url: str, **kwargs: Any) -> Response:
+    return request("HEAD", url, **kwargs)
+
+
+def put(url: str, **kwargs: Any) -> Response:
+    return request("PUT", url, **kwargs)
+
+
+def delete(url: str, **kwargs: Any) -> Response:
+    return request("DELETE", url, **kwargs)

fizzpy/__main__.py

@@ -0,0 +1,235 @@
+"""Command line: ``python -m fizzpy probe HOST...`` (also installed as ``fizzpy``)."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Sequence
+
+from .probe import (
+    NoPostQuantumSupport,
+    Outcome,
+    ProbeResult,
+    Verdict,
+    parse_target,
+    probe_many,
+)
+
+# (column header, group name in ProbeResult.attempts)
+_COLUMNS = (
+    ("ML-KEM", "X25519MLKEM768"),
+    ("x25519", "x25519"),
+    ("P-256", "secp256r1"),
+    ("P-384", "secp384r1"),
+)
+_CELL = {Outcome.ACCEPTED: "ok", Outcome.REJECTED: "rej", Outcome.FAILED: "FAIL"}
+_COLOR = {
+    Verdict.POST_QUANTUM: "32",
+    Verdict.CLASSICAL_ONLY: "33",
+    Verdict.PQ_BLOCKED: "31",
+    Verdict.NO_TLS13: "31",
+    Verdict.UNREACHABLE: "90",
+    Verdict.ERROR: "31",
+}
+
+
+def _paint(text: str, code: str, *, enabled: bool) -> str:
+    return f"\033[{code}m{text}\033[0m" if enabled else text
+
+
+def _cell(result: ProbeResult, group: str) -> str:
+    for attempt in result.attempts:
+        if attempt.offered == (group,):
+            return _CELL[attempt.outcome]
+    return "-"
+
+
+def _row(result: ProbeResult) -> list[str]:
+    target = result.host if result.port == 443 else f"{result.host}:{result.port}"
+    note = result.error or ""
+    return [
+        target,
+        result.verdict.value,
+        result.preferred or "-",
+        *(_cell(result, group) for _, group in _COLUMNS),
+        note,
+    ]
+
+
+def _print_table(results: Sequence[ProbeResult], *, color: bool) -> None:
+    header = ["HOST", "VERDICT", "PREFERRED", *(name for name, _ in _COLUMNS), ""]
+    rows = [header, *(_row(r) for r in results)]
+    widths = [max(len(row[i]) for row in rows) for i in range(len(header))]
+    for i, row in enumerate(rows):
+        cells: list[str] = []
+        for j, text in enumerate(row):
+            padded = text.ljust(widths[j])
+            if i > 0 and j == 1:
+                padded = _paint(padded, _COLOR[results[i - 1].verdict], enabled=color)
+            cells.append(padded)
+        print("  ".join(cells).rstrip())
+
+
+def _print_detail(result: ProbeResult) -> None:
+    where = f" ({result.address}, tcp {result.tcp_ms}ms)" if result.address else ""
+    print(f"\n{result.host}:{result.port}{where} -> {result.verdict.value}")
+    if result.error:
+        print(f"  error: {result.error}")
+    for attempt in (*result.attempts, result.default):
+        if attempt is None:
+            continue
+        label = "default offer" if attempt is result.default else attempt.offered[0]
+        line = f"  {label:<16} {attempt.outcome.value:<9} {attempt.elapsed_ms:>7}ms"
+        if attempt.outcome is Outcome.ACCEPTED:
+            line += f"  {attempt.group} {attempt.cipher} alpn={attempt.alpn}"
+            line += f" cert={attempt.certificate}"
+        elif attempt.alert:
+            line += f"  alert={attempt.alert}"
+        if attempt.detail:
+            line += f"  {attempt.detail}"
+        print(line)
+
+
+def _read_targets(args: argparse.Namespace) -> list[str]:
+    raw: list[str] = list(args.targets)
+    if args.file:
+        if args.file == "-":
+            lines = sys.stdin.read().splitlines()
+        else:
+            with open(args.file, encoding="utf-8-sig") as handle:
+                lines = handle.read().splitlines()
+        raw += [line.split("#", 1)[0].strip() for line in lines]
+    return [t for t in raw if t]
+
+
+async def _probe_all(
+    args: argparse.Namespace, targets: list[tuple[str, int]]
+) -> list[ProbeResult]:
+    results: list[ProbeResult] = []
+    async for result in probe_many(
+        targets, concurrency=args.concurrency, timeout=args.timeout, sni=args.sni
+    ):
+        if args.json:
+            print(json.dumps(result.to_dict()), flush=True)
+        results.append(result)
+    return results
+
+
+def _cmd_probe(args: argparse.Namespace) -> int:
+    try:
+        # Dedup on the parsed target, so Example.com and example.com:443 are one.
+        targets = list(dict.fromkeys(parse_target(t) for t in _read_targets(args)))
+    except (OSError, ValueError) as exc:
+        print(f"fizzpy: {exc}", file=sys.stderr)
+        return 2
+    if not targets:
+        print("fizzpy: no targets given (pass hosts or --file)", file=sys.stderr)
+        return 2
+
+    try:
+        results = asyncio.run(_probe_all(args, targets))
+    except NoPostQuantumSupport as exc:
+        print(f"fizzpy: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+    if not args.json:
+        order = {t: i for i, t in enumerate(targets)}
+        results.sort(key=lambda r: order.get((r.host, r.port), len(order)))
+        # Legacy Windows consoles print escape codes raw, so colour is POSIX-only.
+        color = (
+            sys.stdout.isatty()
+            and sys.platform != "win32"
+            and "NO_COLOR" not in os.environ
+        )
+        _print_table(results, color=color)
+        if args.verbose:
+            for result in results:
+                _print_detail(result)
+
+    if args.require_pq and any(r.verdict is not Verdict.POST_QUANTUM for r in results):
+        return 1
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fizzpy", description="Post-quantum TLS 1.3 tools built on Fizz."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser(
+        "probe",
+        help="check which TLS 1.3 key exchanges a server accepts",
+        description=(
+            "Offer one key-exchange group per connection and report which the server "
+            "accepts. 'rej' means the server answered with a TLS alert; 'FAIL' means "
+            "the connection broke without one (reset, close, timeout). Certificates "
+            "are not validated."
+        ),
+    )
+    p.add_argument(
+        "targets",
+        nargs="*",
+        metavar="TARGET",
+        help="host, host:port, [v6]:port or https:// URL",
+    )
+    p.add_argument(
+        "-f", "--file", help="read targets from FILE, one per line ('-' for stdin)"
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="print one JSON object per target as it finishes",
+    )
+    p.add_argument(
+        "-v", "--verbose", action="store_true", help="show every handshake in detail"
+    )
+    p.add_argument(
+        "-c", "--concurrency", type=int, default=16, help="hosts probed at once (16)"
+    )
+    p.add_argument(
+        "-t",
+        "--timeout",
+        type=float,
+        default=5.0,
+        help="seconds per connect/handshake (5)",
+    )
+    p.add_argument(
+        "--sni",
+        metavar="NAME",
+        help="server name to send for every target (default: the host; none for IPs)",
+    )
+    p.add_argument(
+        "--require-pq",
+        action="store_true",
+        help="exit 1 unless every target is post-quantum",
+    )
+    p.set_defaults(func=_cmd_probe)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "probe" and (args.concurrency < 1 or args.timeout <= 0):
+        print("fizzpy: --concurrency and --timeout must be positive", file=sys.stderr)
+        return 2
+    # A certificate subject can hold characters the terminal's encoding lacks.
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(errors="replace")
+    try:
+        return args.func(args)
+    except BrokenPipeError:
+        # The reader went away (`| head`); aim stdout at devnull so the
+        # interpreter's exit-time flush does not raise again.
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())