nene2-python 1.8.28__tar.gz → 1.8.29__tar.gz

{nene2_python-1.8.28 → nene2_python-1.8.29}/CHANGELOG.md

@@ -5,6 +5,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.28] — 2026-05-20
+
+FT83 フィールドトライアル — Depends() DI パターン検証と PaginationResponse / PaginationDep 改善。
+
+### Added
+- `PaginationResponse.model_dump()` を `to_dict()` の Pydantic 互換エイリアスとして追加 (#355) (FT83)
+  — Pydantic v2 ユーザーが `model_dump()` を期待して AttributeError になる問題を解消
+- `PaginationDep` 型エイリアスを `nene2.http` に追加 (#355) (FT83)
+  — `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の省略形
+- Field trial report: `docs/field-trials/2026-05-field-trial-83.md` (FT83)
+
+---
+
 ## [1.8.27] — 2026-05-20
 
 FT81 フィールドトライアル — CORS 設定パターン検証と setup_middlewares() への CORS 統合。

{nene2_python-1.8.28 → nene2_python-1.8.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.28
+Version: 1.8.29
 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.29/docs/field-trials/2026-05-field-trial-84.md

@@ -0,0 +1,151 @@
+# FT84: 認証 Depends ユーティリティ — CurrentUser / require_auth パターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: nene2.auth に認証 Depends ユーティリティがない摩擦点と make_require_auth 設計検証  
+**バージョン**: v1.8.28  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft84-auth-depends/`
+
+---
+
+## 概要
+
+`LocalTokenVerifier` と `TokenVerifierProtocol` は実装されているが、
+FastAPI の Depends パターンに接続するユーティリティがない。
+ユーザーは `HTTPBearer` → `verify()` → 未認証 401 を毎プロジェクトで手組みする必要がある。
+`make_require_auth(verifier)` ファクトリーを追加することで解消できる。
+
+---
+
+## 発見した問題
+
+### 問題1: 認証 Depends を毎回手組みする必要がある
+
+```python
+# 現状: プロジェクトごとに以下のコードを書く必要がある (50+ 行のボイラープレート)
+
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from nene2.auth import LocalTokenVerifier
+
+security = HTTPBearer(auto_error=False)
+_verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials | None = Depends(security),
+) -> str | None:
+    if credentials is None:
+        return None
+    if not _verifier.verify(credentials.credentials):
+        return None
+    return credentials.credentials
+
+def require_auth(user: str | None = Depends(get_current_user)) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+# ハンドラーで使う
+@app.post("/items")
+def create(body: ItemBody, user: str = Depends(require_auth)) -> JSONResponse: ...
+```
+
+### 問題2: 任意認証パターンが冗長
+
+```python
+# 未認証でも通るが user を取得したいパターン
+def optional_auth(user: str | None = Depends(get_current_user)) -> str | None:
+    return user  # None = 未認証、str = ユーザーID
+
+@app.get("/feed")
+def get_feed(user: str | None = Depends(optional_auth)) -> JSONResponse:
+    if user:
+        return JSONResponse({"personalized": True})
+    return JSONResponse({"personalized": False})
+```
+
+### 問題3: TokenVerifierProtocol を Depends で直接使えない
+
+```python
+# こういう書き方をしたくなるが Depends は callable を期待する
+@app.post("/items")
+def create(
+    body: ItemBody,
+    token: Annotated[str, Depends(LocalTokenVerifier.from_env("TOKENS"))],  # ← 機能しない
+) -> JSONResponse: ...
+```
+
+---
+
+## テスト結果（全12件パス）
+
+```
+test_public_endpoint_no_auth                     PASSED
+test_create_item_with_valid_token                PASSED
+test_create_item_without_token_returns_401       PASSED
+test_create_item_with_invalid_token_returns_401  PASSED
+test_get_me_returns_user_info                    PASSED
+test_delete_item_authenticated                   PASSED
+test_delete_item_unauthenticated_returns_401     PASSED
+test_request_id_present_on_401                  PASSED  # nene2 ミドルウェアと共存
+test_security_headers_present_on_401            PASSED  # nene2 ミドルウェアと共存
+test_friction_boilerplate_for_auth_depends       PASSED  # 摩擦記録
+test_friction_optional_auth_pattern_verbose      PASSED  # 摩擦記録
+test_friction_verifier_not_injectable_as_depends PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F84-1 | 認証 Depends ボイラープレートを毎プロジェクトで手組みする必要がある | 中 |
+| F84-2 | 任意認証（Optional User）パターンが冗長 | 低 |
+| F84-3 | `TokenVerifierProtocol` を Depends で直接使えない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「nene2 でトークン認証を追加する」という操作に必要なステップが多すぎる。
+`BearerTokenMiddleware` は全経路に認証を入れるには便利だが、
+「このエンドポイントだけ認証を要求」パターンに Depends ユーティリティがない。
+FastAPI の HTTPBearer を使う方法は FastAPI のドキュメントを参照しなければわからない。
+
+### 実害の深刻さ ★★★☆☆
+
+認証は多くのプロジェクトで必要。毎回 50 行のボイラープレートを書くのは
+DRY 原則に反する。バグが入りやすく、テスト漏れにもつながる。
+
+### 修正のしやすさ ★★★★★
+
+`make_require_auth(verifier)` 関数を `nene2.auth` に追加するだけ:
+
+```python
+def make_require_auth(verifier: TokenVerifierProtocol) -> Callable[..., str]:
+    security = HTTPBearer(auto_error=False)
+    def get_current_user(credentials: ... = Depends(security)) -> str | None:
+        if credentials is None or not verifier.verify(credentials.credentials):
+            return None
+        return credentials.credentials
+    def require_auth(user: str | None = Depends(get_current_user)) -> str:
+        if user is None:
+            raise HTTPException(status_code=401)
+        return user
+    return require_auth
+```
+
+### 総合コメント
+
+nene2 の認証機能は「ミドルウェアで全経路を保護する」ユースケースは
+`BearerTokenMiddleware` でカバーされている。
+不足しているのは「特定エンドポイントのみ認証を要求する」ユースケース。
+`make_require_auth()` を追加することで「nene2 だけで完結」できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue #358**: `nene2.auth` に `make_require_auth(verifier)` ファクトリーを追加
+   — `require_auth = make_require_auth(LocalTokenVerifier.from_env("TOKENS"))` パターンを実現

{nene2_python-1.8.28 → nene2_python-1.8.29}/pyproject.toml

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

{nene2_python-1.8.28 → nene2_python-1.8.29}/src/nene2/auth/__init__.py

@@ -2,6 +2,7 @@
 
 from .api_key import ApiKeyAuthMiddleware
 from .bearer_token import BearerTokenMiddleware
+from .deps import make_require_auth
 from .exceptions import TokenVerificationException
 from .interfaces import TokenIssuerProtocol, TokenVerifierProtocol
 from .local_verifier import LocalTokenVerifier
@@ -13,4 +14,5 @@ __all__ = [
     "TokenIssuerProtocol",
     "TokenVerificationException",
     "TokenVerifierProtocol",
+    "make_require_auth",
 ]

nene2_python-1.8.29/src/nene2/auth/deps.py

@@ -0,0 +1,50 @@
+"""FastAPI Depends utilities for authentication.
+
+Provides ``make_require_auth`` to wire :class:`TokenVerifierProtocol` into
+FastAPI's dependency injection system without boilerplate.
+"""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from .interfaces import TokenVerifierProtocol
+
+_security = HTTPBearer(auto_error=False)
+
+
+def make_require_auth(verifier: TokenVerifierProtocol) -> Callable[..., str]:
+    """Return a FastAPI Depends-compatible callable that enforces token authentication.
+
+    Usage::
+
+        from nene2.auth import LocalTokenVerifier, make_require_auth
+
+        verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+        require_auth = make_require_auth(verifier)
+
+
+        @app.post("/items")
+        def create_item(
+            body: ItemBody,
+            token: Annotated[str, Depends(require_auth)],
+        ) -> JSONResponse: ...
+
+    Args:
+        verifier: A :class:`TokenVerifierProtocol` implementation to validate tokens.
+
+    Returns:
+        A dependency function that returns the raw token string when authenticated,
+        or raises ``HTTP 401`` when the token is absent or invalid.
+    """
+
+    def _get_token(
+        credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_security)],
+    ) -> str:
+        if credentials is None or not verifier.verify(credentials.credentials):
+            raise HTTPException(status_code=401, detail="Invalid or missing token")
+        return credentials.credentials
+
+    return _get_token

nene2_python-1.8.29/tests/nene2/auth/test_make_require_auth.py

@@ -0,0 +1,99 @@
+"""Tests for make_require_auth() Depends factory."""
+
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from fastapi.responses import JSONResponse
+from fastapi.testclient import TestClient
+
+from nene2.auth import LocalTokenVerifier, make_require_auth
+
+
+def _make_app(tokens: list[str]) -> FastAPI:
+    verifier = LocalTokenVerifier(tokens)
+    require_auth = make_require_auth(verifier)
+
+    app = FastAPI()
+
+    @app.get("/public")
+    def public() -> JSONResponse:
+        return JSONResponse({"public": True})
+
+    @app.get("/protected")
+    def protected(token: Annotated[str, Depends(require_auth)]) -> JSONResponse:
+        return JSONResponse({"token": token})
+
+    @app.post("/items")
+    def create(token: Annotated[str, Depends(require_auth)]) -> JSONResponse:
+        return JSONResponse({"created_by": token[:8]}, status_code=201)
+
+    return app
+
+
+def test_valid_token_returns_200() -> None:
+    client = TestClient(_make_app(["secret-token"]), raise_server_exceptions=False)
+    r = client.get("/protected", headers={"Authorization": "Bearer secret-token"})
+    assert r.status_code == 200
+    assert r.json()["token"] == "secret-token"  # noqa: S105
+
+
+def test_missing_token_returns_401() -> None:
+    client = TestClient(_make_app(["secret-token"]), raise_server_exceptions=False)
+    r = client.get("/protected")
+    assert r.status_code == 401
+
+
+def test_invalid_token_returns_401() -> None:
+    client = TestClient(_make_app(["secret-token"]), raise_server_exceptions=False)
+    r = client.get("/protected", headers={"Authorization": "Bearer wrong-token"})
+    assert r.status_code == 401
+
+
+def test_public_endpoint_no_auth_required() -> None:
+    client = TestClient(_make_app([]), raise_server_exceptions=False)
+    r = client.get("/public")
+    assert r.status_code == 200
+
+
+def test_post_with_valid_token_returns_201() -> None:
+    client = TestClient(_make_app(["my-api-key"]), raise_server_exceptions=False)
+    r = client.post("/items", headers={"Authorization": "Bearer my-api-key"})
+    assert r.status_code == 201
+
+
+def test_multiple_valid_tokens() -> None:
+    client = TestClient(_make_app(["token-a", "token-b"]), raise_server_exceptions=False)
+    r_a = client.get("/protected", headers={"Authorization": "Bearer token-a"})
+    r_b = client.get("/protected", headers={"Authorization": "Bearer token-b"})
+    assert r_a.status_code == 200
+    assert r_b.status_code == 200
+
+
+def test_empty_allowlist_rejects_all() -> None:
+    client = TestClient(_make_app([]), raise_server_exceptions=False)
+    r = client.get("/protected", headers={"Authorization": "Bearer any-token"})
+    assert r.status_code == 401
+
+
+def test_different_verifiers_independent() -> None:
+    """2つの異なる verifier を同じアプリで使える。"""
+    verifier_a = LocalTokenVerifier(["token-a"])
+    verifier_b = LocalTokenVerifier(["token-b"])
+    require_a = make_require_auth(verifier_a)
+    require_b = make_require_auth(verifier_b)
+
+    app = FastAPI()
+
+    @app.get("/route-a")
+    def route_a(token: Annotated[str, Depends(require_a)]) -> JSONResponse:
+        return JSONResponse({"token": token})
+
+    @app.get("/route-b")
+    def route_b(token: Annotated[str, Depends(require_b)]) -> JSONResponse:
+        return JSONResponse({"token": token})
+
+    client = TestClient(app, raise_server_exceptions=False)
+    assert client.get("/route-a", headers={"Authorization": "Bearer token-a"}).status_code == 200
+    assert client.get("/route-a", headers={"Authorization": "Bearer token-b"}).status_code == 401
+    assert client.get("/route-b", headers={"Authorization": "Bearer token-b"}).status_code == 200
+    assert client.get("/route-b", headers={"Authorization": "Bearer token-a"}).status_code == 401

{nene2_python-1.8.28 → nene2_python-1.8.29}/uv.lock

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