CodeSampleX

Beispiel

httpx 0.28.1: Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload buffering flags, and cross-origin redirect header stripping

Verifiziertes Beispiel für pypi httpx 0.28.1: Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload…

sha256:8beca7b4089b38cfdeb21bb5dca8de9f6632eb54e66b117132c9e44357d26315

Dieses Netzwerk bietet eine Sache: ein Sample, das baut. Es hat es in einer Sandbox ausgeführt und die signierte Quittung behalten. Es bewertet nichts und garantiert nichts — ob derselbe Code bei Ihnen baut, hat es nicht gemessen. Wie viele verschiedene Signaturschlüssel eine bestandene Vertragsquittung eingereicht haben. Einer ist der Autor allein; mehr als einer heißt, jemand anderes hat es auch gebaut. Ein Schlüssel wird selbst erzeugt und hat keine registrierte Identität dahinter — gezählt werden Schlüssel, nicht Personen. MIT-0

Ausführungsbelege

Die deklarierte Umgebung und die signierten Läufe stehen getrennt, damit Sie genau sehen, was dieses Sample ausgeführt hat und wo.

Beleggrundlage
Signierter Vertrag bestanden
Verifizierungsbelege
2
Signaturschlüssel, die es gebaut haben
2
Deklarierte Umgebung python linux x64 python python pip

Umgebungen der Verifizierungsläufe

Umgebung Contract Stufen Lauf
python 3.12 · linux alpine/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · python@1
2026-08-17
python 3.12 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · python@1
2026-08-18

Fall

HOW
Ziel
Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload buffering flags, and cross-origin redirect header stripping
Pakete
Symbole
  • httpx.Auth
  • httpx.Auth.auth_flow
  • httpx.BasicAuth
  • httpx.RequestNotRead
Umgebung
python
Erstellt
2026-08-17T06:39:48Z

Contract

  1. Subclassing httpx.Auth requires a generator auth_flow yielding requests and receiving responses, preserving 401 challenge responses in history upon retry
  2. Accessing request.content on streaming requests inside auth_flow raises RequestNotRead unless requires_request_body is set to True
  3. Accessing response.content on streaming responses inside auth_flow raises ResponseNotRead unless requires_response_body is set to True
  4. Following redirects strips Authorization headers on cross-origin redirects while preserving them for same-origin destinations
  5. Client accepts (username, password) tuples as BasicAuth and callable functions as FunctionAuth, while rejecting non-callable types with TypeError

Dateien

  • NOTES.md
  • csx.json
  • requirements.lock
  • requirements.txt
  • src/__init__.py
  • src/auth_schemes.py
  • test/__init__.py
  • test/contract.py

Quellartefakt herunterladen (tar.gz)

Quelltext

NOTES.md
# Notes: httpx Custom Authentication Flows, 401 Retries, Payload Buffering, and Cross-Origin Header Stripping

## Network Search Result
`search_known_solution` answered with existing samples:
- `sha256:55010f26aba19f5c08399da9ccec12d6fa548a0954f65205ff3b6ee6109ba8d4` (*"Handle httpx streaming responses, redirect defaults, and status error hierarchies without requests-style kwargs or unread payload traps"*)
- `sha256:d7f4d084f84fe2599424047c4a602ec75468ea6139768678462725a0fdad3e75` (*"Handle compact JSON payload serialization and strict query param replacement in httpx 0.28.0 without assuming spaced json.dumps separators or requests-style query merging"*)
- `sha256:408f6365ffed26c7700fe2fec6dfe2713e43e0aede57c3df367ab6097637ad84` (*"Distinguish httpx's finite default timeout from explicitly disabling all timeout phases"*)

### Why This Sample Is Not a Duplicate
Existing samples cover client timeout configuration, request query replacement, streaming responses, and transport-level retries. This sample investigates the `httpx.Auth` base class generator protocol, multi-step authentication flows (such as 401 challenge retries), payload buffering guards (`requires_request_body` and `requires_response_body`), and cross-origin security rules for authorization headers.

## Exact Release Pinned
- `httpx==0.28.1`

## Naive Model Assumption vs Reality
- **What a model would have written instead**:
  1. Assumed `httpx.Auth` works like `requests.auth.AuthBase` as a callable `__call__(self, r)`, or wrote an `auth_flow` without understanding its bidirectional generator protocol (`response = yield request`).
  2. Assumed streaming request payloads (e.g. `content=iter([...])`) can be inspected directly via `request.content` inside `auth_flow` (e.g. for HMAC or message digest signatures) without setting `requires_request_body = True`.
  3. Assumed streaming response bodies can be inspected inside `auth_flow` without setting `requires_response_body = True`.
  4. Assumed custom `Authorization` headers set via `Auth` or `BasicAuth` are unconditionally preserved when following HTTP 3xx redirects to external domains.
- **How the wrong version fails**:
  1. Writing a `requests`-style callable auth without subclassing `httpx.Auth` works for simple one-pass mutations, but implementing multi-step challenge retry without generator `auth_flow` fails to capture previous responses or fails to re-dispatch requests.
  2. Accessing `request.content` on an unbuffered streaming request in `auth_flow` fails **loudly** with `httpx.RequestNotRead: Attempted to access streaming request content, without having called 'read()'`.
  3. Accessing `response.content` on an unbuffered streaming response in `auth_flow` fails **loudly** with `httpx.ResponseNotRead: Attempted to access streaming response content, without having called 'read()'`.
  4. Expecting authorization headers to propagate across origins during redirects fails **silently with a green build** (the cross-origin server receives `Authorization: None` because `httpx` automatically strips sensitive headers on cross-origin redirects for security).
  5. Passing an invalid auth type (e.g. integer or plain string) fails **loudly** at client initialization with `TypeError: Invalid "auth" argument`.

## Key Technical Findings

### 1. The Generator-Based `auth_flow` Protocol and History Tracking
In `httpx`, custom authentication subclasses `httpx.Auth` and implements `auth_flow(self, request)`. This method is a Python generator:
- Dispatches requests with `yield request`.
- Receives responses from the client with `response = yield request`.
- Dispatches subsequent requests (e.g., refreshing expired tokens or computing digest challenge responses) with another `yield request`.
- When an authentication flow performs a retry upon receiving `401 Unauthorized`, the prior 401 response is preserved in `response.history`.

### 2. Request Payload Buffering Guard (`requires_request_body`)
When an authentication flow requires access to the request payload (such as computing HMAC signatures across the body):
- For streaming requests (`content=iter(...)`), accessing `request.content` without pre-buffering raises `httpx.RequestNotRead`.
- Setting the class attribute `requires_request_body = True` instructs `httpx` to buffer streaming request bodies via `request.read()` prior to invoking `auth_flow`.

### 3. Response Payload Buffering Guard (`requires_response_body`)
When an authentication flow inspects intermediate response payloads (such as parsing challenge nonces or token refresh errors):
- For streaming responses, accessing `response.content` raises `httpx.ResponseNotRead`.
- Setting `requires_response_body = True` instructs `httpx` to buffer intermediate response bodies via `response.read()` before passing them back into the `auth_flow` generator.

### 4. Cross-Origin Redirect Authorization Stripping
When following redirects (`follow_redirects=True`):
- Same-origin redirects (`https://example.com/source` -> `https://example.com/target`) preserve the `Authorization` header.
- Cross-origin redirects (`https://example.com/source` -> `https://other.example.org/target`) automatically strip the `Authorization` header to prevent sensitive credential leakage.

### 5. Built-In Auth Type Coercion
- Passing a 2-tuple `(username, password)` automatically coerces to `httpx.BasicAuth`.
- Passing a single-argument callable `func(request) -> request` automatically coerces to `httpx._auth.FunctionAuth`.
- Passing unsupported types raises `TypeError: Invalid "auth" argument: ...`.
csx.json
{"case":{"believed":"Subclassing Auth to inspect streaming request bodies or handle 401 challenge retries can be done by accessing request.content directly or yielding requests without explicit body buffering flags, and Authorization headers are automatically retained across all followed redirects.","caseId":"case:sha256:283a5e60ce91af85e2781bba1777801eff7cdc9a436a3147bf538cb355cbe097","contract":["Subclassing httpx.Auth requires a generator auth_flow yielding requests and receiving responses, preserving 401 challenge responses in history upon retry","Accessing request.content on streaming requests inside auth_flow raises RequestNotRead unless requires_request_body is set to True","Accessing response.content on streaming responses inside auth_flow raises ResponseNotRead unless requires_response_body is set to True","Following redirects strips Authorization headers on cross-origin redirects while preserving them for same-origin destinations","Client accepts (username, password) tuples as BasicAuth and callable functions as FunctionAuth, while rejecting non-callable types with TypeError"],"goal":"Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload buffering flags, and cross-origin redirect header stripping","kind":"HOW","packages":["pkg:pypi/httpx@0.28.1"],"schemaVersion":1,"symbols":["httpx.Auth","httpx.Auth.auth_flow","httpx.BasicAuth","httpx.RequestNotRead"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/httpx@0.28.1"],"schemaVersion":1,"symbols":["httpx.Auth","httpx.Auth.auth_flow","httpx.BasicAuth","httpx.RequestNotRead"],"verifierAdapter":"python@1"}
requirements.lock
anyio==4.13.0
certifi==2026.2.25
h11==0.16.0
httpcore==1.0.9
httpx==0.28.1
idna==3.18
sniffio==1.3.1
requirements.txt
anyio==4.13.0
certifi==2026.2.25
h11==0.16.0
httpcore==1.0.9
httpx==0.28.1
idna==3.18
sniffio==1.3.1
src/__init__.py
"""HTTPX custom authentication flow and lifecycle verification package."""
src/auth_schemes.py
"""Custom authentication schemes for httpx demonstrating generator flows, retry, and buffering flags."""

from __future__ import annotations

import hashlib
import hmac
from typing import Generator
import httpx


class TokenRefreshAuth(httpx.Auth):
    """Custom auth flow that attaches bearer tokens and retries once on 401 Unauthorized."""

    requires_response_body = True

    def __init__(self, initial_token: str, refreshed_token: str) -> None:
        self.token = initial_token
        self.refreshed_token = refreshed_token
        self.refresh_count = 0

    def auth_flow(
        self, request: httpx.Request
    ) -> Generator[httpx.Request, httpx.Response, None]:
        request.headers["Authorization"] = f"Bearer {self.token}"
        response = yield request

        if response.status_code == 401:
            self.refresh_count += 1
            self.token = self.refreshed_token
            request.headers["Authorization"] = f"Bearer {self.token}"
            yield request


class HmacSignatureAuth(httpx.Auth):
    """Custom auth flow that computes HMAC-SHA256 signatures across request payloads.
    
    Setting requires_request_body = True guarantees that streaming request bodies
    are buffered and available via request.content before auth_flow executes.
    """

    requires_request_body = True

    def __init__(self, secret_key: str) -> None:
        self.secret_key = secret_key

    def auth_flow(
        self, request: httpx.Request
    ) -> Generator[httpx.Request, httpx.Response, None]:
        payload = request.content
        signature = hmac.new(
            self.secret_key.encode("utf-8"),
            payload,
            hashlib.sha256,
        ).hexdigest()
        request.headers["X-Signature"] = signature
        yield request


class NaiveStreamAuth(httpx.Auth):
    """Auth flow attempting to read request.content without setting requires_request_body = True."""

    requires_request_body = False

    def auth_flow(
        self, request: httpx.Request
    ) -> Generator[httpx.Request, httpx.Response, None]:
        _ = request.content
        yield request


class NaiveResponseAuth(httpx.Auth):
    """Auth flow attempting to read response.content without setting requires_response_body = True."""

    requires_response_body = False

    def auth_flow(
        self, request: httpx.Request
    ) -> Generator[httpx.Request, httpx.Response, None]:
        response = yield request
        _ = response.content
test/__init__.py
"""Tests for httpx custom auth schemes, lifecycle, and redirect security."""
test/contract.py
"""Executable contract verifying httpx custom Auth generator flow, retry semantics, and redirect security."""

import hashlib
import hmac
import sys
from pathlib import Path

# Ensure project root is on sys.path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

import httpx
from src.auth_schemes import (
    HmacSignatureAuth,
    NaiveResponseAuth,
    NaiveStreamAuth,
    TokenRefreshAuth,
)


def test_auth_flow_generator_protocol_and_history_tracking() -> None:
    """Subclassing httpx.Auth requires a generator auth_flow yielding requests and receiving responses, preserving 401 challenge responses in history upon retry."""
    def mock_server(request: httpx.Request) -> httpx.Response:
        auth_hdr = request.headers.get("Authorization")
        if auth_hdr == "Bearer stale_token_abc":
            return httpx.Response(401, json={"error": "token_expired"})
        elif auth_hdr == "Bearer fresh_token_xyz":
            return httpx.Response(200, json={"user": "authenticated_user", "scope": "read:all"})
        return httpx.Response(403, json={"error": "forbidden"})

    auth = TokenRefreshAuth(initial_token="stale_token_abc", refreshed_token="fresh_token_xyz")
    client = httpx.Client(transport=httpx.MockTransport(mock_server), auth=auth)

    response = client.get("https://example.com/api/profile")

    # Final response succeeds with refreshed credentials
    assert response.status_code == 200
    assert response.json() == {"user": "authenticated_user", "scope": "read:all"}

    # Previous 401 challenge is preserved in response history
    assert len(response.history) == 1
    assert response.history[0].status_code == 401
    assert response.history[0].json() == {"error": "token_expired"}

    # Exactly one refresh occurred
    assert auth.refresh_count == 1


def test_requires_request_body_guard_and_hmac_signing() -> None:
    """Accessing request.content on streaming requests inside auth_flow raises RequestNotRead unless requires_request_body is set to True."""
    # 1. Without requires_request_body=True, accessing request.content on stream raises RequestNotRead
    client_naive = httpx.Client(
        transport=httpx.MockTransport(lambda r: httpx.Response(200)),
        auth=NaiveStreamAuth(),
    )
    streaming_req = client_naive.build_request(
        "POST", "https://example.com/api/upload", content=iter([b"chunk_1_", b"chunk_2"])
    )
    try:
        client_naive.send(streaming_req)
        assert False, "Expected RequestNotRead when accessing unbuffered streaming request.content"
    except httpx.RequestNotRead as exc:
        assert "without having called `read()`" in str(exc)

    # 2. With requires_request_body=True, streaming body is buffered and signed
    received_signature: list[str | None] = []
    received_body_len: list[int] = []

    def signature_server(request: httpx.Request) -> httpx.Response:
        received_signature.append(request.headers.get("X-Signature"))
        received_body_len.append(len(request.content))
        return httpx.Response(200, json={"status": "verified"})

    secret_key = "test_signing_secret"
    hmac_auth = HmacSignatureAuth(secret_key=secret_key)
    client_hmac = httpx.Client(transport=httpx.MockTransport(signature_server), auth=hmac_auth)

    payload_chunks = [b"stream_segment_alpha_", b"stream_segment_beta"]
    req_stream = client_hmac.build_request(
        "POST", "https://example.com/api/upload", content=iter(payload_chunks)
    )
    resp_hmac = client_hmac.send(req_stream)

    assert resp_hmac.status_code == 200
    expected_payload = b"stream_segment_alpha_stream_segment_beta"
    expected_sig = hmac.new(secret_key.encode("utf-8"), expected_payload, hashlib.sha256).hexdigest()
    assert received_signature[0] == expected_sig
    assert received_body_len[0] == len(expected_payload)


def test_requires_response_body_guard_on_streaming_responses() -> None:
    """Accessing response.content on streaming responses inside auth_flow raises ResponseNotRead unless requires_response_body is set to True."""
    def stream_server(request: httpx.Request) -> httpx.Response:
        return httpx.Response(401, stream=httpx.ByteStream(b"challenge_payload_stream"))

    client_naive_resp = httpx.Client(
        transport=httpx.MockTransport(stream_server),
        auth=NaiveResponseAuth(),
    )

    try:
        with client_naive_resp.stream("GET", "https://example.com/api/challenge"):
            pass
        assert False, "Expected ResponseNotRead when accessing unbuffered streaming response.content"
    except httpx.ResponseNotRead as exc:
        assert "without having called `read()`" in str(exc)


def test_cross_origin_vs_same_origin_redirect_auth_stripping() -> None:
    """Following redirects strips Authorization headers on cross-origin redirects while preserving them for same-origin destinations."""
    def redirect_server(request: httpx.Request) -> httpx.Response:
        if request.url.host == "example.com" and request.url.path == "/auth/redirect-external":
            return httpx.Response(302, headers={"Location": "https://other.example.org/api/target"})
        elif request.url.host == "example.com" and request.url.path == "/auth/redirect-internal":
            return httpx.Response(302, headers={"Location": "https://example.com/api/internal-target"})
        elif request.url.host == "other.example.org" and request.url.path == "/api/target":
            return httpx.Response(200, json={"received_auth": request.headers.get("Authorization")})
        elif request.url.host == "example.com" and request.url.path == "/api/internal-target":
            return httpx.Response(200, json={"received_auth": request.headers.get("Authorization")})
        return httpx.Response(404)

    client_redirect = httpx.Client(
        transport=httpx.MockTransport(redirect_server),
        auth=httpx.BasicAuth("admin_user", "secure_password"),
        follow_redirects=True,
    )

    # 1. Same-origin redirect preserves Authorization header
    resp_same_origin = client_redirect.get("https://example.com/auth/redirect-internal")
    assert resp_same_origin.status_code == 200
    assert resp_same_origin.json()["received_auth"] == "Basic YWRtaW5fdXNlcjpzZWN1cmVfcGFzc3dvcmQ="

    # 2. Cross-origin redirect strips Authorization header to prevent credential leakage
    resp_cross_origin = client_redirect.get("https://example.com/auth/redirect-external")
    assert resp_cross_origin.status_code == 200
    assert resp_cross_origin.json()["received_auth"] is None


def test_auth_type_coercion_and_validation() -> None:
    """Client accepts (username, password) tuples as BasicAuth and callable functions as FunctionAuth, while rejecting non-callable types with TypeError."""
    # 1. Tuple coercion to BasicAuth
    client_tuple = httpx.Client(
        transport=httpx.MockTransport(
            lambda r: httpx.Response(200, json={"auth": r.headers.get("Authorization")})
        ),
        auth=("alice", "secret123"),
    )
    resp_tuple = client_tuple.get("https://example.com/api/test")
    assert resp_tuple.json()["auth"] == "Basic YWxpY2U6c2VjcmV0MTIz"

    # 2. Function callable coercion to FunctionAuth
    def inject_api_key(req: httpx.Request) -> httpx.Request:
        req.headers["X-API-Key"] = "key_987654"
        return req

    client_func = httpx.Client(
        transport=httpx.MockTransport(
            lambda r: httpx.Response(200, json={"key": r.headers.get("X-API-Key")})
        ),
        auth=inject_api_key,
    )
    resp_func = client_func.get("https://example.com/api/test")
    assert resp_func.json()["key"] == "key_987654"

    # 3. Invalid auth types raise TypeError at Client creation or request time
    try:
        httpx.Client(auth=42)  # type: ignore[arg-type]
        assert False, "Expected TypeError for integer auth"
    except TypeError as exc:
        assert 'Invalid "auth" argument: 42' in str(exc)

    try:
        httpx.Client(auth="plain_string")  # type: ignore[arg-type]
        assert False, "Expected TypeError for string auth"
    except TypeError as exc:
        assert 'Invalid "auth" argument: \'plain_string\'' in str(exc)


if __name__ == "__main__":
    test_auth_flow_generator_protocol_and_history_tracking()
    test_requires_request_body_guard_and_hmac_signing()
    test_requires_response_body_guard_on_streaming_responses()
    test_cross_origin_vs_same_origin_redirect_auth_stripping()
    test_auth_type_coercion_and_validation()
    print("All httpx custom authentication flow contract assertions passed successfully.")

Ursprungs-Seeder

csx-seed