nene2-python 1.8.11__tar.gz → 1.8.13__tar.gz

{nene2_python-1.8.11 → nene2_python-1.8.13}/CHANGELOG.md

@@ -5,6 +5,28 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.13] — 2026-05-20
+
+FT53 フィールドトライアル — ApiKeyAuthMiddleware 実運用検証 + header_name パラメータ追加。
+
+### Added
+- `ApiKeyAuthMiddleware` に `header_name: str = "X-Api-Key"` パラメータを追加 — カスタムヘッダー名 (`X-Service-Token` 等) を指定可能に。エラーメッセージにも `header_name` が反映される (#286) (FT53)
+- Field trial report: `docs/field-trials/2026-05-field-trial-53.md`
+
+---
+
+## [1.8.12] — 2026-05-20
+
+FT52 フィールドトライアル — ミドルウェアスタック組み合わせ検証 + LocalTokenVerifier 改善。
+
+### Changed
+- `LocalTokenVerifier.__init__` — `allowed_tokens` の型を `list[str] | set[str] | frozenset[str]` に変更。内部で `frozenset` に変換し `in` 演算が O(1) になった (#284) (FT52)
+
+### Added
+- Field trial report: `docs/field-trials/2026-05-field-trial-52.md`
+
+---
+
 ## [1.8.11] — 2026-05-20
 
 FT51 フィールドトライアル — SimpleDomainHandler 実運用検証 + problem_details_response バグ修正。

{nene2_python-1.8.11 → nene2_python-1.8.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.11
+Version: 1.8.13
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.13/docs/field-trials/2026-05-field-trial-52.md

@@ -0,0 +1,90 @@
+# Field Trial 52: ミドルウェアスタック組み合わせ検証
+
+**Date**: 2026-05-20
+**Theme**: 全ミドルウェアスタック (BearerToken + Throttle + RequestLogging + SecurityHeaders) の組み合わせ実運用
+**Version under test**: v1.8.11
+**FT App**: `/home/xi/docker/nene2-python-FT/ft52-middleware-stack/`
+
+---
+
+## 概要
+
+`ErrorHandlerMiddleware` + `SecurityHeadersMiddleware` + `RequestIdMiddleware` +
+`RequestLoggingMiddleware` + `ThrottleMiddleware` + `BearerTokenMiddleware` を
+全スタックで積み重ねて動作を検証した。
+
+---
+
+## 実装内容
+
+### ミドルウェアスタック
+
+```python
+app.add_middleware(ErrorHandlerMiddleware)
+app.add_middleware(SecurityHeadersMiddleware, csp="default-src 'self'", hsts="max-age=31536000")
+app.add_middleware(RequestIdMiddleware)
+app.add_middleware(RequestLoggingMiddleware, exclude_paths=["/health"], extra_context={"service": "ft52", "env": "test"})
+app.add_middleware(ThrottleMiddleware, limit=5, window=60, exclude_paths=["/health"])
+app.add_middleware(BearerTokenMiddleware, verifier=verifier, exclude_paths=["/health", "/docs", "/openapi.json"])
+```
+
+`/health` は認証・ログ・レート制限をすべてバイパスする設計。
+
+---
+
+## テスト結果
+
+10 tests, all passed (after fixing FP52-1).
+
+| テスト | 結果 |
+|---|---|
+| /health は認証不要 | ✅ |
+| /items は認証必須 | ✅ |
+| 有効トークンで /items アクセス | ✅ |
+| セキュリティヘッダー存在確認 | ✅ |
+| HSTS ヘッダー確認 | ✅ |
+| X-Request-Id ヘッダー確認 | ✅ |
+| X-RateLimit-Limit ヘッダー確認 | ✅ |
+| /health はレート制限なし (10回連続) | ✅ |
+| レート制限超過で 429 | ✅ |
+| 無効トークンで 401 | ✅ |
+
+---
+
+## 摩擦ポイント
+
+### FP52-1: `LocalTokenVerifier` の引数名が直感的でない / `set` 非対応
+
+**状況**: `LocalTokenVerifier(valid_tokens={valid_token})` と書いたが:
+1. 引数名は `valid_tokens` ではなく `allowed_tokens`
+2. `set` を渡すと型エラー（内部が `list[str]` を期待）
+
+**修正**: `allowed_tokens` の型を `list[str] | set[str] | frozenset[str]` に変更し、
+内部で `frozenset` に変換するよう修正 (#284)。
+内部を `frozenset` にすることで `in` 演算の O(n) → O(1) 改善も得られた。
+
+---
+
+## フレームワーク変更
+
+### `LocalTokenVerifier` — `set` / `frozenset` を受け入れ可能に (#284)
+
+```python
+# 修正前
+def __init__(self, allowed_tokens: list[str]) -> None:
+    self._allowed = allowed_tokens
+
+# 修正後
+def __init__(self, allowed_tokens: list[str] | set[str] | frozenset[str]) -> None:
+    self._allowed: frozenset[str] = frozenset(allowed_tokens)
+```
+
+---
+
+## 全スタック動作確認
+
+各ミドルウェアの機能がスタック状態でも正常に動作することを確認:
+- `exclude_paths` の設定が各ミドルウェアで独立して機能する
+- `BearerTokenMiddleware` が `ThrottleMiddleware` より外側（先に評価）
+- `SecurityHeadersMiddleware` のヘッダーが全レスポンスに付与される
+- `RequestIdMiddleware` の `X-Request-Id` が全レスポンスに付与される

nene2_python-1.8.13/docs/field-trials/2026-05-field-trial-53.md

@@ -0,0 +1,81 @@
+# Field Trial 53: ApiKeyAuthMiddleware 実運用検証
+
+**Date**: 2026-05-20
+**Theme**: `ApiKeyAuthMiddleware` の実運用パターン検証
+**Version under test**: v1.8.12
+**FT App**: `/home/xi/docker/nene2-python-FT/ft53-api-key-auth/`
+
+---
+
+## 概要
+
+`ApiKeyAuthMiddleware` + `LocalTokenVerifier(set)` の組み合わせを複数 API キー対応の
+サービスで実運用した。`exclude_paths` と `RequestIdMiddleware` との組み合わせも検証。
+
+---
+
+## 実装内容
+
+```python
+verifier = LocalTokenVerifier({"key-dev-001", "key-dev-002"})
+app.add_middleware(
+    ApiKeyAuthMiddleware,
+    verifier=verifier,
+    exclude_paths=["/health", "/docs", "/openapi.json", "/redoc"],
+)
+```
+
+---
+
+## テスト結果
+
+9 tests, all passed.
+
+---
+
+## 摩擦ポイント
+
+### FP53-1: `ApiKeyAuthMiddleware` のヘッダー名が `X-Api-Key` に固定されている
+
+**状況**: サービスによっては `X-Service-Token` や `X-Internal-Key` など
+異なるヘッダー名を使いたい場合がある。
+
+**修正**: `header_name: str = "X-Api-Key"` パラメータを追加 (#286)。
+
+```python
+app.add_middleware(
+    ApiKeyAuthMiddleware,
+    verifier=verifier,
+    header_name="X-Service-Token",  # カスタムヘッダー名
+)
+```
+
+エラーメッセージにも `header_name` が反映される:
+```
+"A valid X-Service-Token header is required."
+```
+
+**補足**: HTTP ヘッダーは RFC 7230 で大文字小文字無視であるため、
+`X-API-KEY` / `X-Api-Key` などの大文字小文字の違いは問題にならない。
+
+---
+
+## フレームワーク変更
+
+### `ApiKeyAuthMiddleware` — `header_name` パラメータを追加 (#286)
+
+```python
+# デフォルト動作（後方互換）
+ApiKeyAuthMiddleware(verifier=verifier)  # X-Api-Key を使用
+
+# カスタムヘッダー名
+ApiKeyAuthMiddleware(verifier=verifier, header_name="X-Service-Token")
+```
+
+---
+
+## 結論
+
+`ApiKeyAuthMiddleware` は `LocalTokenVerifier(set)` との組み合わせで
+複数 API キーを管理する用途で問題なく動作する。
+`header_name` パラメータの追加で柔軟性が向上した。

{nene2_python-1.8.11 → nene2_python-1.8.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.11"
+version = "1.8.13"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}

{nene2_python-1.8.11 → nene2_python-1.8.13}/src/nene2/auth/api_key.py

@@ -1,6 +1,6 @@
 """API Key authentication middleware.
 
-Validates X-Api-Key header using a TokenVerifierProtocol.
+Validates a configurable header (default: X-Api-Key) using a TokenVerifierProtocol.
 Returns 401 Problem Details when key is absent or invalid.
 """
 
@@ -13,18 +13,18 @@ from nene2.http.problem_details import problem_details_response
 from .exceptions import TokenVerificationException
 from .interfaces import TokenVerifierProtocol
 
-_API_KEY_HEADER = "X-Api-Key"
+_DEFAULT_API_KEY_HEADER = "X-Api-Key"
 
 
 class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
-    """Require a valid X-Api-Key header on every request.
+    """Require a valid API key header on every request.
 
-    Use ``exclude_paths`` to skip authentication for specific paths such as
-    health-check endpoints or API documentation::
+    The header name defaults to ``X-Api-Key`` but can be customised::
 
         app.add_middleware(
             ApiKeyAuthMiddleware,
             verifier=LocalTokenVerifier(api_keys),
+            header_name="X-Service-Token",
             exclude_paths=["/docs", "/openapi.json", "/redoc", "/health"],
         )
     """
@@ -34,16 +34,18 @@ class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
         app: object,
         *,
         verifier: TokenVerifierProtocol,
+        header_name: str = _DEFAULT_API_KEY_HEADER,
         exclude_paths: list[str] | None = None,
     ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._verifier = verifier
+        self._header_name = header_name
         self._exclude_paths = set(exclude_paths or [])
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
         if request.url.path in self._exclude_paths:
             return await call_next(request)
-        api_key = request.headers.get(_API_KEY_HEADER, "")
+        api_key = request.headers.get(self._header_name, "")
         try:
             verified = bool(api_key) and self._verifier.verify(api_key)
         except TokenVerificationException:
@@ -53,6 +55,6 @@ class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
                 "unauthorized",
                 "Unauthorized",
                 401,
-                "A valid X-Api-Key header is required.",
+                f"A valid {self._header_name} header is required.",
             )
         return await call_next(request)

{nene2_python-1.8.11 → nene2_python-1.8.13}/src/nene2/auth/local_verifier.py

@@ -11,8 +11,8 @@ import secrets
 class LocalTokenVerifier:
     """Verify tokens against a fixed allowlist using constant-time comparison."""
 
-    def __init__(self, allowed_tokens: list[str]) -> None:
-        self._allowed = allowed_tokens
+    def __init__(self, allowed_tokens: list[str] | set[str] | frozenset[str]) -> None:
+        self._allowed: frozenset[str] = frozenset(allowed_tokens)
 
     @classmethod
     def from_env(cls, env_var: str, *, separator: str = ",") -> "LocalTokenVerifier":

{nene2_python-1.8.11 → nene2_python-1.8.13}/tests/nene2/auth/test_api_key.py

@@ -87,3 +87,38 @@ def test_verifier_raises_token_verification_exception_returns_401() -> None:
     client = TestClient(app, raise_server_exceptions=False)
     response = client.get("/secret", headers={"X-Api-Key": "any-key"})
     assert response.status_code == 401
+
+
+def test_custom_header_name() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["svc-token"]),
+        header_name="X-Service-Token",
+    )
+
+    @app.get("/secret")
+    async def secret() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app, raise_server_exceptions=False)
+    assert client.get("/secret", headers={"X-Service-Token": "svc-token"}).status_code == 200
+    assert client.get("/secret", headers={"X-Api-Key": "svc-token"}).status_code == 401
+
+
+def test_custom_header_name_in_error_message() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["tok"]),
+        header_name="X-Internal-Key",
+    )
+
+    @app.get("/secret")
+    async def secret() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app, raise_server_exceptions=False)
+    response = client.get("/secret")
+    assert response.status_code == 401
+    assert "X-Internal-Key" in response.json().get("detail", "")

{nene2_python-1.8.11 → nene2_python-1.8.13}/tests/nene2/auth/test_bearer_token.py

@@ -113,3 +113,16 @@ def test_exclude_paths_default_is_empty() -> None:
 
     client = TestClient(app)
     assert client.get("/health").status_code == 401
+
+
+def test_local_verifier_accepts_set() -> None:
+    verifier = LocalTokenVerifier({"tok-a", "tok-b"})
+    assert verifier.verify("tok-a") is True
+    assert verifier.verify("tok-b") is True
+    assert verifier.verify("tok-c") is False
+
+
+def test_local_verifier_accepts_frozenset() -> None:
+    verifier = LocalTokenVerifier(frozenset({"tok-x", "tok-y"}))
+    assert verifier.verify("tok-x") is True
+    assert verifier.verify("unknown") is False

{nene2_python-1.8.11 → nene2_python-1.8.13}/uv.lock

@@ -925,7 +925,7 @@ wheels = [
 
 [[package]]
 name = "nene2-python"
-version = "1.8.11"
+version = "1.8.13"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },