fizzpy 0.3.0__tar.gz

fizzpy-0.3.0/.github/manylinux-deps.Dockerfile

@@ -0,0 +1,16 @@
+# Manylinux base image with the folly + fizz + liboqs tree prebuilt, so wheel
+# builds skip the ~40-min source build and just compile _core against it. Rebuilt
+# by .github/workflows/manylinux-image.yml when build_fizz_deps.py or FIZZ_TAG
+# changes. The dep prefixes land in $FIZZPY_BUILD_INFO/prefix.txt, which CMake
+# reads at configure time (see CMakeLists.txt).
+ARG MANYLINUX_IMAGE=quay.io/pypa/manylinux_2_28_x86_64:latest
+FROM ${MANYLINUX_IMAGE}
+
+ARG FIZZ_TAG=v2026.06.08.00
+ENV FIZZ_TAG=${FIZZ_TAG} \
+    GETDEPS_SCRATCH=/opt/fizz-deps \
+    FIZZPY_BUILD_INFO=/opt/fizzpy-build \
+    FIZZ_SRC=/opt/fizz-src
+
+COPY scripts/build_fizz_deps.py /opt/build_fizz_deps.py
+RUN python3 /opt/build_fizz_deps.py

fizzpy-0.3.0/.github/workflows/check.yml

@@ -0,0 +1,38 @@
+name: Check
+
+on:
+  push:
+    branches: [master]
+    tags-ignore: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      # _core.pyi lets ruff and basedpyright run without the native build.
+      - name: Sync toolchain
+        run: uv sync --no-install-project --group dev
+
+      - name: Lint
+        run: uv run --no-sync ruff check --output-format=github .
+
+      - name: Format
+        run: uv run --no-sync ruff format --check .
+
+      - name: Type check
+        run: uv run --no-sync basedpyright

fizzpy-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # Reuse the wheel/sdist build so a tag produces exactly the artifacts CI
+  # already validates on every push. packages: write lets the deps_image job
+  # rebuild the image if a tag introduces a deps change with no prior push.
+  build:
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/wheels.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    # OIDC token for PyPI Trusted Publishing — no API token/secret required.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

fizzpy-0.3.0/.github/workflows/wheels.yml

@@ -0,0 +1,118 @@
+name: Wheels
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The folly+fizz+liboqs tree is baked into a GHCR image tagged by the hash of
+  # its build inputs. This job rebuilds it only when that hash has no image yet
+  # (deps changed, or first run); otherwise it's a fast existence check. Wheels
+  # depend on it, so they never run against a missing image.
+  deps_image:
+    name: Deps image
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      image: ${{ steps.meta.outputs.image }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Resolve image ref
+        id: meta
+        env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          repo="ghcr.io/${OWNER,,}/fizz-py-deps"
+          tag="${{ hashFiles('scripts/build_fizz_deps.py', '.github/manylinux-deps.Dockerfile') }}"
+          echo "repo=$repo" >> "$GITHUB_OUTPUT"
+          echo "image=$repo:$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check whether the image already exists
+        id: exists
+        run: |
+          if docker manifest inspect "${{ steps.meta.outputs.image }}" > /dev/null 2>&1; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push deps image
+        if: steps.exists.outputs.found == 'false'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: .github/manylinux-deps.Dockerfile
+          push: true
+          tags: |
+            ${{ steps.meta.outputs.image }}
+            ${{ steps.meta.outputs.repo }}:latest
+
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - run: pipx run build --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    # One job per interpreter, each compiling _core against the prebuilt deps
+    # image (minutes, not ~40 min). liboqs travels with fizz's getdeps manifest,
+    # giving real post-quantum (X25519MLKEM768) support.
+    name: Wheel ${{ matrix.python }}
+    needs: deps_image
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [cp310, cp311, cp312, cp313, cp314]
+    steps:
+      - uses: actions/checkout@v6
+
+      # cibuildwheel pulls the deps image via docker; authenticate so the GHCR
+      # package is reachable.
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build wheel
+        uses: pypa/cibuildwheel@v4.1.0
+        env:
+          CIBW_BUILD: ${{ matrix.python }}-*
+          CIBW_MANYLINUX_X86_64_IMAGE: ${{ needs.deps_image.outputs.image }}
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.python }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error

fizzpy-0.3.0/.gitignore

@@ -0,0 +1,46 @@
+build/
+CMakeFiles/
+dist/
+.dev/
+_skbuild/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app

fizzpy-0.3.0/.vscode/c_cpp_properties.json

@@ -0,0 +1,19 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**",
+                "${workspaceFolder}/build/vcpkg_installed/**",
+                "/usr/include/python3.10/**"
+            ],
+            "defines": [],
+            "compilerPath": "/usr/bin/clang",
+            "cStandard": "c17",
+            "cppStandard": "c++20",
+            "intelliSenseMode": "linux-clang-x64",
+            "configurationProvider": "ms-vscode.cmake-tools"
+        }
+    ],
+    "version": 4
+}

fizzpy-0.3.0/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "files.associations": {
+        "*.ipp": "cpp",
+        "*.tcc": "cpp",
+        "optional": "cpp",
+        "system_error": "cpp",
+        "regex": "cpp"
+    },
+    "cSpell.words": [
+        "fizzpy"
+    ]
+}

fizzpy-0.3.0/BUILDING.md

@@ -0,0 +1,57 @@
+# Building fizzpy
+
+The `_core` extension links Facebook's Fizz (C++ TLS 1.3). The post-quantum
+handshake additionally requires a Fizz built against
+[liboqs](https://github.com/open-quantum-safe/liboqs) — the Homebrew bottle and
+vcpkg port both ship `FIZZ_HAVE_OQS=0`, so they negotiate classical groups only.
+
+There are two build paths, for two different purposes:
+
+| | Local dev (`just build`) | CI wheels (`scripts/build_fizz_deps.py`) |
+| --- | --- | --- |
+| Fizz/liboqs source | Homebrew + from-source Fizz | getdeps, all from source |
+| Linkage | static Fizz, shared liboqs via rpath | fully static-PIC, self-contained `.so` |
+| Where | your machine | `manylinux_2_28` container |
+| Optimized for | fast iteration | deterministic, portable distribution |
+
+## Local development (`just`)
+
+```sh
+brew install fizz liboqs    # fizz pulls folly, boost, glog, gflags, libsodium, double-conversion
+pip install -e .[dev] --no-build-isolation   # or: pip install scikit-build-core pybind11 pybind11-stubgen ruff pytest
+
+just build      # build OQS Fizz if needed (cached), then editable-install _core
+just test       # offline test suite; `just test ""` includes live network tests
+just check      # ruff lint
+just fmt        # ruff format + clang-format _core.cpp
+```
+
+`just build` runs `scripts/build_fizz.py ensure`, which compiles a liboqs-enabled
+Fizz into the gitignored `.dev/fizz-prefix` once (subsequent runs are a no-op;
+`python scripts/build_fizz.py ensure --force` rebuilds), then editable-installs
+`_core` with `find_package(fizz)` pointed at that prefix.
+
+- **C++20 is required** — current Folly (2026.06) dropped C++17.
+- Fizz and Folly are versioned together. The tag in `scripts/build_fizz.py` must
+  match the Homebrew Folly bottle, or the ABI won't match.
+- `find_package(liboqs CONFIG)` inside Fizz auto-sets `FIZZ_HAVE_OQS` and links
+  `OQS::oqs`. `BUILD_EXAMPLES=OFF` is required: the bundled FizzTool fails to
+  compile under OpenSSL 3.6 (`-Werror` on the deprecated `EVP_PKEY_cmp`); the
+  library itself is fine.
+
+## Portable wheels (CI)
+
+`scripts/build_fizz_deps.py` is cibuildwheel's `before-all`. It builds the whole
+folly + Fizz + liboqs tree once per `manylinux_2_28` container as static-PIC
+archives, which `_core` links in wholesale — a single self-contained extension
+with exactly one copy of folly. (Using getdeps `--shared-lib` instead would bake
+folly into `libfizz.so` *and* drag it into `_core` again, double-registering
+folly's gflags globals and aborting at import.) The build settings live in
+`[tool.cibuildwheel]` in `pyproject.toml`.
+
+## Verify
+
+```sh
+python -c "import fizzpy; print(fizzpy.get('https://www.cloudflare.com').tls)"
+# group should be 'X25519MLKEM768', group_code 4588
+```

fizzpy-0.3.0/CMakeLists.txt

@@ -0,0 +1,88 @@
+cmake_minimum_required(VERSION 3.15...3.27)
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+project(
+  ${SKBUILD_PROJECT_NAME}
+  VERSION ${SKBUILD_PROJECT_VERSION}
+  LANGUAGES CXX)
+
+# Only Linux x86_64 wheels are published. Stop here before the (~40 min) folly +
+# fizz + liboqs source build that an sdist install would otherwise attempt and
+# fail on macOS/Windows.
+if(NOT CMAKE_SYSTEM_NAME STREQUAL "Linux")
+  message(
+    FATAL_ERROR
+    "fizzpy publishes prebuilt Linux x86_64 wheels only; ${CMAKE_SYSTEM_NAME} "
+    "is not yet supported. Building from source needs the Fizz toolchain — see "
+    "BUILDING.md (https://github.com/Xevion/fizz-py/blob/master/BUILDING.md).")
+endif()
+
+# Fizz's CMake config pulls in its bundled FindSodium.cmake. Homebrew installs
+# it under libexec/cmake; make that discoverable for local (non-vcpkg) builds.
+# Override with -DFIZZ_CMAKE_MODULE_DIR=... if your install differs.
+set(FIZZ_CMAKE_MODULE_DIR "/home/linuxbrew/.linuxbrew/opt/fizz/libexec/cmake"
+    CACHE PATH "Directory containing Fizz's bundled CMake find-modules")
+if(EXISTS "${FIZZ_CMAKE_MODULE_DIR}")
+  list(APPEND CMAKE_MODULE_PATH "${FIZZ_CMAKE_MODULE_DIR}")
+endif()
+
+if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
+  set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+      CACHE STRING "")
+endif()
+
+message(STATUS "Using compiler: ${CMAKE_CXX_COMPILER}")
+
+# Portable-wheel builds: scripts/build_fizz_deps.py (cibuildwheel before-all)
+# writes the getdeps install prefixes and fizz's find-module dir here. Read them
+# at configure time rather than as a CIBW environment substitution, which would
+# evaluate before before-all has produced the files. Skipped for local builds,
+# which pass -DCMAKE_PREFIX_PATH directly (see BUILDING.md).
+if(DEFINED ENV{FIZZPY_BUILD_INFO})
+  set(_info "$ENV{FIZZPY_BUILD_INFO}")
+  if(EXISTS "${_info}/prefix.txt")
+    file(STRINGS "${_info}/prefix.txt" _fizz_prefix)
+    list(APPEND CMAKE_PREFIX_PATH ${_fizz_prefix})
+  endif()
+  if(EXISTS "${_info}/module_dir.txt")
+    file(STRINGS "${_info}/module_dir.txt" _fizz_modules)
+    list(APPEND CMAKE_MODULE_PATH ${_fizz_modules})
+  endif()
+endif()
+
+# pybind11 is pip-installed (locally, or by before-build in wheel builds); add its
+# CMake config so find_package locates it without a CIBW env substitution.
+# Development.Module must be in this first find_package: pybind11's NewTools skips
+# its own Python discovery once Python_FOUND is set, so python_add_library (from
+# Development.Module) would otherwise never be defined.
+find_package(Python COMPONENTS Interpreter Development.Module QUIET)
+if(Python_Interpreter_FOUND)
+  execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m pybind11 --cmakedir
+    OUTPUT_VARIABLE _pybind11_cmakedir
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET)
+  if(_pybind11_cmakedir)
+    list(APPEND CMAKE_PREFIX_PATH "${_pybind11_cmakedir}")
+  endif()
+endif()
+
+set(PYBIND11_NEWPYTHON ON)
+find_package(pybind11 CONFIG REQUIRED)
+find_package(fizz CONFIG REQUIRED)
+
+pybind11_add_module(_core _core.cpp)
+target_link_libraries(_core PRIVATE fizz::fizz)
+
+# _core.cpp drives connections on a folly::ScopedEventBaseThread, but fizz itself
+# never uses that type — so when folly is a static archive (e.g. getdeps
+# --shared-lib portable wheels), its object never makes it into libfizz and the
+# symbol is undefined at import. Link the component directly when folly exposes
+# it as a discrete target; classic shared-folly builds (Homebrew) export it from
+# libfolly already and skip this.
+if(TARGET Folly::folly_io_async_scoped_event_base_thread)
+  target_link_libraries(_core PRIVATE Folly::folly_io_async_scoped_event_base_thread)
+endif()
+
+install(TARGETS _core LIBRARY DESTINATION fizzpy)

fizzpy-0.3.0/Justfile

@@ -0,0 +1,35 @@
+# fizzpy dev tasks. `just build` is the fast local loop (editable _core against
+# a liboqs-enabled Fizz); CI wheels are built separately via scripts/build_fizz_deps.py.
+
+_default:
+    @just --list
+
+# Build the OQS Fizz prefix if needed, then editable-install _core against it.
+build:
+    python scripts/build_fizz.py ensure
+    pip install -e . --no-build-isolation --config-settings=build-dir=.dev/build-editable --config-settings=cmake.define.CMAKE_PREFIX_PATH="$(python scripts/build_fizz.py prefix-path)"
+
+# Build a non-editable wheel and force-reinstall it (full install, not the editable loop).
+wheel:
+    python -m build
+    pip install ./dist/*.whl --force-reinstall
+
+# Run the test suite. Defaults to the offline, deterministic subset; pass args to
+# override, e.g. `just test ""` for the full suite (needs network).
+test *args="-m 'not network'":
+    pytest {{args}}
+
+# Install the lint/type toolchain into .venv without building _core.
+_tools:
+    uv sync --no-install-project --group dev
+
+# Lint and type-check Python.
+check: _tools
+    uv run --no-sync ruff check .
+    uv run --no-sync ruff format --check .
+    uv run --no-sync basedpyright
+
+# Format Python and C++ in place.
+fmt: _tools
+    uv run --no-sync ruff format .
+    clang-format -i _core.cpp

fizzpy-0.3.0/LICENSE

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

fizzpy-0.3.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: fizzpy
+Version: 0.3.0
+Summary: A low-level TLS 1.3 client toolkit for Python, built on Facebook's Fizz
+Author-Email: Xevion <xevion@xevion.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Project-URL: Repository, https://github.com/Xevion/fizz-py
+Project-URL: Issues, https://github.com/Xevion/fizz-py/issues
+Requires-Python: >=3.10
+Requires-Dist: certifi
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Description-Content-Type: text/markdown
+
+# fizzpy
+
+A small TLS 1.3 HTTP client for Python, built on Facebook's
+[Fizz](https://github.com/facebookincubator/fizz) (C++) via pybind11.
+
+By default it offers a **post-quantum key exchange** — the standardized hybrid
+`X25519MLKEM768` group (codepoint 4588). An ordinary `GET` negotiates a hybrid
+ML-KEM handshake against servers that support it (Cloudflare, Google) and falls
+back to classical X25519 against those that don't.
+
+> TLS 1.3 only, HTTP/1.1 only. This is a focused toolkit / learning project,
+> not a drop-in `requests` replacement. See [Status](#status).
+
+![A fizzpy ClientHello in Wireshark](docs/pq-handshake.png)
+
+*A fizzpy request captured in Wireshark: the TLS 1.3 ClientHello offers the
+post-quantum `X25519MLKEM768` group (`0x11ec`), and a custom marker extension
+(`0xFE5A`, [see below](#custom-clienthello-extensions)) makes it unmistakably
+ours — generated by [`examples/pq_marker.py`](examples/pq_marker.py).*
+
+## Install
+
+```sh
+pip install fizzpy
+```
+
+The Linux wheels are self-contained: folly, Fizz, and liboqs are statically
+linked into the extension, so a fresh `pip install` has working post-quantum
+TLS with no system packages to add. `certifi` (pulled in automatically) supplies
+the default trust store.
+
+Wheels are produced by CI (`manylinux_2_28`, x86_64, CPython 3.10–3.14); if one
+isn't available for your platform yet, build from source — see
+[BUILDING.md](BUILDING.md).
+
+## Usage
+
+Synchronous:
+
+```python
+import fizzpy
+
+r = fizzpy.get("https://www.cloudflare.com")
+print(r.status_code)               # 200
+print(r.headers["content-type"])   # text/html; charset=UTF-8
+print(r.text[:64])
+
+# The negotiated TLS 1.3 parameters are attached to every response:
+print(r.tls)
+# {'version': 'TLSv1.3', 'cipher': 'TLS_AES_128_GCM_SHA256',
+#  'group': 'X25519MLKEM768', 'group_code': 4588,
+#  'alpn': 'http/1.1', 'sni': 'www.cloudflare.com', 'peer_cert': '...'}
+```
+
+Asynchronous (the same C++ core, resolved on the running event loop):
+
+```python
+import asyncio
+from fizzpy.aio import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        r = await client.get("https://www.google.com")
+        print(r.status_code, r.tls["group"], r.tls["group_code"])
+
+asyncio.run(main())
+```
+
+### Choosing the key exchange
+
+The default offers `[x25519_mlkem768, x25519]`, mirroring how Chrome and Firefox
+send both key shares. Override it per client:
+
+```python
+import fizzpy
+from fizzpy import NamedGroup
+
+# Force post-quantum only (handshake fails if the server lacks ML-KEM):
+pq = fizzpy.Client(groups=[NamedGroup.x25519_mlkem768])
+
+# Classical only:
+classical = fizzpy.Client(groups=[NamedGroup.x25519])
+```
+
+### Custom ClientHello extensions
+
+fizzpy surfaces Fizz's low-level extension hook, so you can append arbitrary
+extensions to the TLS 1.3 ClientHello. Each is an opaque `(type, data)` pair;
+fizzpy rejects types it manages itself (key_share, supported_versions, …) and
+out-of-range or duplicate types.
+
+```python
+import fizzpy
+
+client = fizzpy.Client(
+    extensions=[fizzpy.Extension(0xFE5A, b"hello from fizzpy")],
+)
+r = client.get("https://blog.cloudflare.com")
+print(r.tls["group"])   # still negotiates X25519MLKEM768
+```
+
+The extension is sent verbatim in the ClientHello — see it on the wire with
+[`examples/pq_marker.py`](examples/pq_marker.py) and the screenshot above.
+
+### Certificate verification
+
+Certificate chains are verified against the [certifi](https://github.com/certifi/python-certifi)
+CA bundle and the hostname is checked against the certificate's SAN by default.
+Point at a custom CA, or disable verification entirely:
+
+```python
+fizzpy.Client(cafile="/path/to/ca.pem")   # trust a specific CA
+fizzpy.Client(verify=False)               # accept any certificate (insecure)
+```
+
+## Status
+
+What works today:
+
+- TLS 1.3 handshake with classical or post-quantum (ML-KEM) key exchange
+- `GET`/`POST`/`HEAD`/`PUT`/`DELETE`, sync and async
+- HTTP/1.1 response framing (content-length, chunked, gzip/deflate)
+- Connection keep-alive with a per-host pool; automatic redirect following
+- Chain + hostname certificate verification, certifi default + custom CA trust
+
+Current limitations:
+
+- **TLS 1.3 only** (a Fizz constraint) — it cannot talk to TLS 1.2-only servers
+- HTTP/1.1 only (no HTTP/2)
+
+## Building
+
+The post-quantum handshake requires a Fizz built against
+[liboqs](https://github.com/open-quantum-safe/liboqs). The CI wheels build the
+whole folly + Fizz + liboqs tree from source inside `manylinux_2_28`; see
+[BUILDING.md](BUILDING.md) for that recipe and for local development builds.