サンプル
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
検証済みサンプル — pypi httpx 0.28.1: Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload buffering flags…
sha256:8beca7b4089b38cfdeb21bb5dca8de9f6632eb54e66b117132c9e44357d26315
このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。
合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。
MIT-0
実行証拠
宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。
- 証拠の基準
- 署名済みコントラクト合格
- 検証レシート
- 2
- ビルドした署名鍵
- 2
宣言された環境
python linux x64 python python pip
検証実行環境
| 環境 | コントラクト | ステージ | 実行日 |
|---|---|---|---|
| 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 |
ケース
HOW- ゴール
- Implement custom authentication in httpx via generator-based auth_flow, handling 401 challenge retries, payload buffering flags, and cross-origin redirect header stripping
- パッケージ
- シンボル
-
- httpx.Auth
- httpx.Auth.auth_flow
- httpx.BasicAuth
- httpx.RequestNotRead
- 環境
- python
- 作成日
- 2026-08-17T06:39:48Z
コントラクト
- 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
ファイル
- NOTES.md
- csx.json
- requirements.lock
- requirements.txt
- src/__init__.py
- src/auth_schemes.py
- test/__init__.py
- test/contract.py
ソース
# 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: ...`.
{"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"}
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
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
"""HTTPX custom authentication flow and lifecycle verification package."""
"""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
"""Tests for httpx custom auth schemes, lifecycle, and redirect security."""
"""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.")