nene2-python 1.8.21__tar.gz → 1.8.23__tar.gz

{nene2_python-1.8.21 → nene2_python-1.8.23}/CHANGELOG.md

@@ -5,6 +5,18 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.22] — 2026-05-20
+
+FT76 フィールドトライアル — async def + sync DB ブロッキング問題と run_in_threadpool 追加。
+
+### Added
+- `run_in_threadpool` を `nene2.use_case` から re-export (#326) (FT76)
+  — Starlette の `run_in_threadpool` を nene2 公開 API として公開し、
+  `async def` ハンドラーから同期 DB 処理を安全にスレッドプールへオフロードできる
+- Field trial report: `docs/field-trials/2026-05-field-trial-76.md` (FT76)
+
+---
+
 ## [1.8.21] — 2026-05-20
 
 FT75 フィールドトライアル — ミドルウェアスタック順序問題の発見と根本解決。

{nene2_python-1.8.21 → nene2_python-1.8.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.21
+Version: 1.8.23
 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.23/docs/field-trials/2026-05-field-trial-76.md

@@ -0,0 +1,152 @@
+# FT76: async ハンドラー + sync SQLAlchemy のイベントループブロッキング
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI の async def ハンドラー内で同期 DB 処理を呼ぶとどうなるか  
+**バージョン**: v1.8.21  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft76-async-sync-db/`
+
+---
+
+## 概要
+
+FastAPI は `async def` と `def` を混在できるが、同期処理の扱いが根本的に異なる。
+nene2 の DB 層（`SqlAlchemyQueryExecutor` / `SqlAlchemyTransactionManager`）は同期実装のため、
+`async def` ハンドラー内から直接呼ぶとイベントループをブロックする。
+このFTでは3パターンの挙動を実測し、nene2 として何を提供すべきかを検証した。
+
+---
+
+## テスト対象の3パターン
+
+| パターン | 実装 | 動作 |
+|---|---|---|
+| A | `async def` 内で `time.sleep()` / 同期DB直呼び | **イベントループをブロック** |
+| B | `async def` 内で `run_in_executor()` 経由 | スレッドプールにオフロード（安全） |
+| C | `def` ハンドラー（同期） | FastAPI が自動でスレッドプールに退避（安全） |
+
+---
+
+## 発見した問題
+
+### 問題1: async ハンドラー + sync DB = サイレントブロッキング
+
+```python
+# ❌ よくある間違い
+@app.post("/tasks")
+async def create_task(body: TaskBody) -> JSONResponse:
+    result = _create_task_sync(body.title)  # time.sleep / Session(...) など
+    return JSONResponse(result, status_code=201)
+```
+
+`async def` 内で `time.sleep()` や同期 `Session` を呼ぶと、実行中は asyncio のイベントループが
+完全に停止する。他のリクエストはそのリクエストが完了するまで待たされる。
+
+**特に危険なのは「少量のデータなら問題が出ない」点**。
+開発中 / ステージング環境では顕在化せず、本番で同時アクセスが増えてから遅延が爆発する。
+
+### 問題2: nene2 に async DB 層がない
+
+```python
+# v1.8.21 時点: 存在しない
+from nene2.database import AsyncSqlAlchemyQueryExecutor  # ImportError
+```
+
+`SqlAlchemyQueryExecutor.fetch_all()` / `SqlAlchemyTransactionManager.begin()` は
+すべて同期実装。async def ハンドラーと組み合わせるには自前で `run_in_executor` を書く必要がある。
+
+### 問題3: run_in_executor パターンが冗長で発見しにくい
+
+```python
+# ✅ 正しいが、毎回これを書くのは辛い
+@app.post("/tasks")
+async def create_task(body: TaskBody) -> JSONResponse:
+    loop = asyncio.get_event_loop()
+    result = await loop.run_in_executor(None, _create_task_sync, body.title, body.simulate_ms)
+    return JSONResponse(result, status_code=201)
+```
+
+- `asyncio.get_event_loop()` は Python 3.10+ で deprecation warning を出すことがある
+- `None` の意味（default executor = ThreadPoolExecutor）が自明でない
+- 複数の引数を渡すには `functools.partial` か lambda が必要になりさらに冗長になる
+
+### 問題4: `def` ハンドラーが実は最もシンプルで安全
+
+```python
+# ✅ sync def は FastAPI が自動でスレッドプールに退避する
+@app.post("/tasks")
+def create_task(body: TaskBody) -> JSONResponse:
+    result = _create_task_sync(body.title)  # 安全
+    return JSONResponse(result, status_code=201)
+```
+
+`async def` を書く必然性がないなら `def` を使うべきだが、
+「FastAPI = async」というイメージから全ハンドラーを `async def` にするユーザーが多い。
+nene2 のドキュメントがこれを明示していない。
+
+---
+
+## テスト結果（全12件パス）
+
+```
+test_sync_in_async_creates_task     PASSED  # パターンA: 機能はする（ブロッキングだが）
+test_executor_creates_task          PASSED  # パターンB: executor 経由
+test_sync_def_creates_task          PASSED  # パターンC: sync def
+test_list_tasks                     PASSED
+test_sync_def_does_not_block_event_loop  PASSED  # イベントループが自由であることを確認
+test_sync_in_async_blocks_when_slow     PASSED  # 200ms スリープがそのまま待機時間になる
+test_executor_avoids_blocking           PASSED
+test_middlewares_work_with_all_patterns PASSED  # setup_middlewares() は全パターンで動作
+test_422_on_invalid_title_length        PASSED
+test_422_on_negative_simulate_ms        PASSED
+test_no_async_db_layer_in_nene2         PASSED  # 非同期DB層が存在しないことを確認
+test_threadpool_pattern_is_verbose      PASSED  # 冗長さのドキュメンタリーテスト
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F76-1 | nene2 に async DB 層がなく、async ハンドラーでは run_in_executor が必要 | 高 |
+| F76-2 | async def + sync DB のブロッキングがサイレント（警告なし） | 高 |
+| F76-3 | run_in_executor の書き方が冗長で、正しい引数渡しが分かりにくい | 中 |
+| F76-4 | ドキュメントが async def vs def の使い分けを説明していない | 中 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「FastAPI を使っているので全ハンドラーを async def にする」のは自然な発想。
+しかし nene2 の DB 層は同期なので、これが罠になる。
+`async def` で書いたコードが正常に動き、テストも全部通る — でも本番では爆発する。
+「動いているから正しい」と思ってしまう構造が非常にやっかいで直感に反する。
+
+### 実害の深刻さ ★★★★☆
+
+本番環境で同時アクセスが増えてからはじめて顕在化する。
+レスポンスが遅い → サーバーがダウン、という流れをたどる典型的なパフォーマンス地雷。
+「なぜか重い」「スケールしない」という症状で現れるため、根本原因の特定も遅れやすい。
+
+### 修正のしやすさ ★★☆☆☆
+
+`run_in_executor` パターンを知っていれば直せるが、記述が冗長で毎回ハンドラーに書くのはつらい。
+根本解決（async DB 層の実装）はSQLAlchemy async対応が必要で、工数が大きい。
+`def` ハンドラーへの移行が最もシンプルだが、`async` 依存のロジックが混在していると難しい。
+
+### 総合コメント
+
+FastAPI + SQLAlchemy の組み合わせは最も多いユースケースの一つ。
+「nene2 を使えばすぐ始められる」が「パフォーマンス問題で詰まる」という流れは
+ユーザー離れを引き起こす可能性がある。
+`def` vs `async def` の使い分けガイドラインと、将来的な async DB サポートが必要。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `async def` ハンドラー内での `SqlAlchemy` 同期呼び出し警告をドキュメントに追加
+2. **Issue**: `run_in_threadpool()` ヘルパー（または `asyncify()` パターン）の提供
+3. **将来**: `AsyncSqlAlchemyQueryExecutor` の実装（SQLAlchemy 2.0 async 対応）

nene2_python-1.8.23/docs/field-trials/2026-05-field-trial-77.md

@@ -0,0 +1,179 @@
+# FT77: BearerToken + ApiKey 混在認証
+
+**日付**: 2026-05-20  
+**テーマ**: 同一アプリで認証方式を混在させる — `/admin/*` は JWT Bearer、`/webhook/*` は API Key  
+**バージョン**: v1.8.22  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft77-mixed-auth/`
+
+---
+
+## 概要
+
+実運用では「認証方式がルートによって異なる」は非常に一般的なニーズ。
+nene2 の `BearerTokenMiddleware` と `ApiKeyAuthMiddleware` を混在させる方法を検証した。
+ミドルウェアはアプリ全体をカバーするため、`exclude_paths` を使った回避策が必要で、
+ここに大きな摩擦があることが判明した。
+
+---
+
+## 実装したパターン
+
+```
+/admin/*   → BearerTokenMiddleware（JWT Bearer 必須）
+/webhook/* → ApiKeyAuthMiddleware（X-Api-Key 必須）
+/public/*  → 認証不要
+```
+
+### 設定コード
+
+```python
+app.add_middleware(
+    BearerTokenMiddleware,
+    verifier=admin_verifier,
+    exclude_paths=[
+        "/docs", "/openapi.json", "/redoc", "/health",
+        "/public/hello", "/public/status",
+        "/webhook/event", "/webhook/ping",  # ← webhook は除外
+    ],
+)
+
+app.add_middleware(
+    ApiKeyAuthMiddleware,
+    verifier=webhook_verifier,
+    exclude_paths=[
+        "/docs", "/openapi.json", "/redoc", "/health",
+        "/public/hello", "/public/status",
+        "/admin/dashboard", "/admin/users",  # ← admin は除外
+    ],
+)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: exclude_paths の二重管理
+
+認証対象でないパスを **各ミドルウェアに個別に列挙** しなければならない。
+
+- 新しい `/admin/settings` ルートを追加 → `ApiKeyAuthMiddleware` の `exclude_paths` にも追加必要
+- 忘れると: Bearer トークンを持っていても、API Key がないため 401 になる
+- **サイレント障害**: 認証エラーなので「なぜ 401？」と混乱しやすい
+
+### 問題2: exclude_paths はルートではなく完全一致パス
+
+`exclude_paths` はプレフィックスマッチングをサポートしない。
+
+```python
+# ❌ プレフィックスマッチしない
+exclude_paths=["/admin"]  # /admin/dashboard にマッチしない
+
+# ✅ 完全一致のみ
+exclude_paths=["/admin/dashboard", "/admin/users"]  # 各パスを列挙
+```
+
+ルート数が増えると管理が煩雑になる。
+
+### 問題3: per-route 認証デコレーターがない
+
+FastAPI の Depends() パターンでルートごとに認証を指定することが nene2 では直接できない。
+
+```python
+# FastAPI 標準 (nene2 提供なし)
+from fastapi.security import HTTPBearer
+security = HTTPBearer()
+
+@app.get("/admin/dashboard")
+def admin(token = Depends(security)):
+    ...
+```
+
+nene2 でこれをやるには生の FastAPI `Depends()` を使う必要があり、
+nene2 の `TokenVerifierProtocol` との統合方法が不明瞭。
+
+### 問題4: 「どちらかで認証」が実現できない
+
+Bearer でも API Key でも OK という「OR 認証」がミドルウェア方式では実現困難。
+
+```
+# 現状では:
+BearerMiddleware: 対象パスはBearer必須
+ApiKeyMiddleware: 対象パスはApiKey必須
+
+# 実現できない:
+"Bearer OR ApiKey どちらかがあれば OK"
+```
+
+---
+
+## テスト結果（全17件パス）
+
+```
+test_public_hello_no_auth               PASSED  # 公開エンドポイント
+test_public_status_no_auth              PASSED
+test_health_no_auth                     PASSED
+test_admin_with_valid_bearer            PASSED  # 正常認証
+test_admin_without_auth_returns_401     PASSED
+test_admin_with_invalid_bearer_returns_401  PASSED
+test_admin_with_api_key_instead_of_bearer_returns_401  PASSED  # 認証方式が違う
+test_admin_users_with_valid_bearer      PASSED
+test_webhook_with_valid_api_key         PASSED
+test_webhook_without_auth_returns_401   PASSED
+test_webhook_with_invalid_api_key_returns_401  PASSED
+test_webhook_with_bearer_instead_of_api_key_returns_401  PASSED
+test_admin_with_both_headers_bearer_wins  PASSED  # 両方送ると適切に処理
+test_webhook_with_both_headers_apikey_wins  PASSED
+test_friction_new_admin_route_needs_exclude_update  PASSED  # 摩擦の記録
+test_friction_exclude_paths_is_per_middleware  PASSED
+test_nene2_has_no_per_route_auth_decorator  PASSED  # per-route 機能なし確認
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F77-1 | exclude_paths の二重管理 — 新ルートを追加するたびに各ミドルウェアを更新 | 高 |
+| F77-2 | exclude_paths がプレフィックスマッチをサポートしない（完全一致のみ）| 中 |
+| F77-3 | per-route 認証デコレーターがない — Depends() との統合方法が不明 | 中 |
+| F77-4 | Bearer OR ApiKey の OR 認証が実現できない | 中 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「ミドルウェアは全体をカバーする」という原則は理解できる。
+しかし「特定のルートだけ認証したい」という非常に一般的なニーズに、
+`exclude_paths` という「否定のリスト」で対応するのは直感に反する。
+
+Express の `passport.authenticate()` や Spring Security の `requestMatchers()` は
+「守りたいパスを指定」するモデル。nene2 は「除外するパスを指定」という逆のモデルで混乱しやすい。
+
+### 実害の深刻さ ★★★★☆
+
+新しいルートを追加したとき、`exclude_paths` の更新を忘れると **サイレントな認証エラー** が発生する。
+本番でユーザーが急に 401 になり、コードを読んでも一見問題がないように見える。
+ミドルウェアの設定を疑わないと根本原因に辿り着けない。
+
+### 修正のしやすさ ★★★☆☆
+
+根本解決は「プレフィックスマッチ対応」または「per-route auth」の提供。
+プレフィックスマッチは小さな変更で実現できる。
+per-route auth の提供は FastAPI Depends() との統合が必要で中程度の工数。
+
+### 総合コメント
+
+「守りたいパスのプレフィックスを指定する」モデルへの転換が最も効果的。
+`include_paths: list[str] | None` または `path_prefix: str` パラメーターを追加するだけで、
+「`/admin` 以下は全部 Bearer 必須」と書けるようになり、UX が大幅に改善する。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `BearerTokenMiddleware` / `ApiKeyAuthMiddleware` に `include_paths` または `path_prefixes` パラメーターを追加
+2. **Issue**: `exclude_paths` にプレフィックスマッチ（`/admin/*` 形式）をサポート
+3. **将来**: `nene2.auth` に FastAPI `Depends()` 統合ヘルパーを提供

{nene2_python-1.8.21 → nene2_python-1.8.23}/pyproject.toml

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

{nene2_python-1.8.21 → nene2_python-1.8.23}/src/nene2/auth/api_key.py

@@ -17,10 +17,30 @@ _DEFAULT_API_KEY_HEADER = "X-Api-Key"
 
 
 class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
-    """Require a valid API key header on every request.
+    """Require a valid API key header on matching requests.
 
-    The header name defaults to ``X-Api-Key`` but can be customised::
+    The header name defaults to ``X-Api-Key`` but can be customised.
 
+    **Path filtering** — two complementary options (mutually exclusive):
+
+    - ``include_paths``: only protect paths whose prefix matches one of these values.
+      All other paths pass through without authentication.
+      Ideal for protecting a specific sub-tree (e.g. ``["/webhook"]``).
+    - ``exclude_paths``: protect every path **except** these exact paths.
+      Ideal for skipping docs / health endpoints.
+
+    When both are provided, ``include_paths`` takes precedence.
+
+    Examples::
+
+        # Protect only /webhook/* routes (prefix match)
+        app.add_middleware(
+            ApiKeyAuthMiddleware,
+            verifier=LocalTokenVerifier(api_keys),
+            include_paths=["/webhook"],
+        )
+
+        # Protect everything except docs/health (exact match)
         app.add_middleware(
             ApiKeyAuthMiddleware,
             verifier=LocalTokenVerifier(api_keys),
@@ -36,14 +56,21 @@ class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
         verifier: TokenVerifierProtocol,
         header_name: str = _DEFAULT_API_KEY_HEADER,
         exclude_paths: list[str] | None = None,
+        include_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 [])
+        self._include_paths = list(include_paths or [])
+
+    def _should_authenticate(self, path: str) -> bool:
+        if self._include_paths:
+            return any(path.startswith(prefix) for prefix in self._include_paths)
+        return path not in self._exclude_paths
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
-        if request.url.path in self._exclude_paths:
+        if not self._should_authenticate(request.url.path):
             return await call_next(request)
         api_key = request.headers.get(self._header_name, "")
         try:

{nene2_python-1.8.21 → nene2_python-1.8.23}/src/nene2/auth/bearer_token.py

@@ -17,11 +17,28 @@ _WWW_AUTH = 'Bearer realm="api"'
 
 
 class BearerTokenMiddleware(BaseHTTPMiddleware):
-    """Require a valid Bearer token on every request.
+    """Require a valid Bearer token on matching requests.
 
-    Use ``exclude_paths`` to skip authentication for specific paths such as
-    health-check endpoints or API documentation::
+    **Path filtering** — two complementary options (mutually exclusive):
 
+    - ``include_paths``: only protect paths whose prefix matches one of these values.
+      All other paths pass through without authentication.
+      Ideal for protecting a specific sub-tree (e.g. ``["/admin"]``).
+    - ``exclude_paths``: protect every path **except** these exact paths.
+      Ideal for skipping docs / health endpoints.
+
+    When both are provided, ``include_paths`` takes precedence.
+
+    Examples::
+
+        # Protect only /admin/* routes (prefix match)
+        app.add_middleware(
+            BearerTokenMiddleware,
+            verifier=LocalTokenVerifier(tokens),
+            include_paths=["/admin"],
+        )
+
+        # Protect everything except docs/health (exact match)
         app.add_middleware(
             BearerTokenMiddleware,
             verifier=LocalTokenVerifier(tokens),
@@ -35,13 +52,20 @@ class BearerTokenMiddleware(BaseHTTPMiddleware):
         *,
         verifier: TokenVerifierProtocol,
         exclude_paths: list[str] | None = None,
+        include_paths: list[str] | None = None,
     ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._verifier = verifier
         self._exclude_paths = set(exclude_paths or [])
+        self._include_paths = list(include_paths or [])
+
+    def _should_authenticate(self, path: str) -> bool:
+        if self._include_paths:
+            return any(path.startswith(prefix) for prefix in self._include_paths)
+        return path not in self._exclude_paths
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
-        if request.url.path in self._exclude_paths:
+        if not self._should_authenticate(request.url.path):
             return await call_next(request)
         auth = request.headers.get("Authorization", "")
         if not auth.startswith("Bearer "):

{nene2_python-1.8.21 → nene2_python-1.8.23}/src/nene2/use_case/__init__.py

@@ -1,5 +1,7 @@
 """UseCase contracts — synchronous and asynchronous Protocol definitions."""
 
+from starlette.concurrency import run_in_threadpool
+
 from .protocols import AsyncUseCaseProtocol, UseCaseProtocol
 
-__all__ = ["AsyncUseCaseProtocol", "UseCaseProtocol"]
+__all__ = ["AsyncUseCaseProtocol", "UseCaseProtocol", "run_in_threadpool"]

{nene2_python-1.8.21 → nene2_python-1.8.23}/tests/nene2/auth/test_api_key.py

@@ -122,3 +122,72 @@ def test_custom_header_name_in_error_message() -> None:
     response = client.get("/secret")
     assert response.status_code == 401
     assert "X-Internal-Key" in response.json().get("detail", "")
+
+
+# ---------------------------------------------------------------------------
+# include_paths tests
+# ---------------------------------------------------------------------------
+def test_include_paths_protects_matching_prefix() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["key"]),
+        include_paths=["/webhook"],
+    )
+
+    @app.get("/webhook/event")
+    async def webhook_event() -> JSONResponse:
+        return JSONResponse({"received": True})
+
+    @app.get("/public/hello")
+    async def public_hello() -> JSONResponse:
+        return JSONResponse({"hello": True})
+
+    client = TestClient(app)
+    assert client.get("/webhook/event").status_code == 401
+    assert client.get("/webhook/event", headers={"X-Api-Key": "key"}).status_code == 200
+    assert client.get("/public/hello").status_code == 200
+
+
+def test_include_paths_multiple_prefixes() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["key"]),
+        include_paths=["/webhook", "/internal"],
+    )
+
+    @app.get("/webhook/x")
+    async def webhook_x() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    @app.get("/internal/y")
+    async def internal_y() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    @app.get("/public/z")
+    async def public_z() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.get("/webhook/x").status_code == 401
+    assert client.get("/internal/y").status_code == 401
+    assert client.get("/public/z").status_code == 200
+
+
+def test_include_paths_takes_precedence_over_exclude_paths() -> None:
+    """両方指定されたときは include_paths が優先される。"""
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["key"]),
+        include_paths=["/webhook"],
+        exclude_paths=["/webhook/open"],  # include_paths があるので無視される
+    )
+
+    @app.get("/webhook/open")
+    async def webhook_open() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.get("/webhook/open").status_code == 401

{nene2_python-1.8.21 → nene2_python-1.8.23}/tests/nene2/auth/test_bearer_token.py

@@ -126,3 +126,84 @@ 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
+
+
+# ---------------------------------------------------------------------------
+# include_paths tests
+# ---------------------------------------------------------------------------
+def _make_app_with_include_paths(tokens: list[str], include_paths: list[str]) -> FastAPI:
+    app = FastAPI()
+    app.add_middleware(
+        BearerTokenMiddleware,
+        verifier=LocalTokenVerifier(tokens),
+        include_paths=include_paths,
+    )
+
+    @app.get("/admin/dashboard")
+    async def admin_dashboard() -> JSONResponse:
+        return JSONResponse({"admin": True})
+
+    @app.get("/public/hello")
+    async def public_hello() -> JSONResponse:
+        return JSONResponse({"hello": True})
+
+    return app
+
+
+def test_include_paths_protects_matching_prefix() -> None:
+    client = TestClient(_make_app_with_include_paths(["tok"], ["/admin"]))
+    assert client.get("/admin/dashboard").status_code == 401
+    assert (
+        client.get("/admin/dashboard", headers={"Authorization": "Bearer tok"}).status_code == 200
+    )
+
+
+def test_include_paths_skips_non_matching_prefix() -> None:
+    """include_paths にないパスは認証なしで通過する。"""
+    client = TestClient(_make_app_with_include_paths(["tok"], ["/admin"]))
+    assert client.get("/public/hello").status_code == 200
+
+
+def test_include_paths_multiple_prefixes() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        BearerTokenMiddleware,
+        verifier=LocalTokenVerifier(["tok"]),
+        include_paths=["/admin", "/private"],
+    )
+
+    @app.get("/admin/x")
+    async def admin_x() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    @app.get("/private/y")
+    async def private_y() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    @app.get("/public/z")
+    async def public_z() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.get("/admin/x").status_code == 401
+    assert client.get("/private/y").status_code == 401
+    assert client.get("/public/z").status_code == 200
+
+
+def test_include_paths_takes_precedence_over_exclude_paths() -> None:
+    """両方指定されたときは include_paths が優先される。"""
+    app = FastAPI()
+    app.add_middleware(
+        BearerTokenMiddleware,
+        verifier=LocalTokenVerifier(["tok"]),
+        include_paths=["/admin"],
+        exclude_paths=["/admin/open"],  # include_paths があるので無視される
+    )
+
+    @app.get("/admin/open")
+    async def admin_open() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    # include_paths=["/admin"] が優先 → /admin/open も保護される
+    assert client.get("/admin/open").status_code == 401