nene2-python 1.3.0__tar.gz → 1.4.0__tar.gz

{nene2_python-1.3.0 → nene2_python-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.3.0
+Version: 1.4.0
 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.4.0/docs/field-trials/2026-05-field-trial-11.md

@@ -0,0 +1,116 @@
+# Field Trial 11 — journal: BearerTokenMiddleware + HttpxMcpClient DX 検証
+
+## Date
+
+2026-05-20
+
+## Baseline
+
+- nene2-python v1.3.0（PyPI 経由）
+- Python 3.14（uv managed）
+- プロジェクト: **journal** — 日記管理 API
+- エンティティ: `Entry(id, title, body, created_at)`
+- HTTP API: ポート 8120（BearerTokenMiddleware 付き、InMemory）
+- MCP サーバー: ポート 8121（streamable-http）
+
+## Goal
+
+FT9 で `HttpxMcpClient` の基本（認証なし）は確認済み。
+今回は `BearerTokenMiddleware` で保護した HTTP API に対して MCP ツールが認証付きリクエストを送るパターンを検証する。
+
+---
+
+## Steps Taken
+
+### 1. BearerTokenMiddleware で HTTP API を保護
+
+```python
+tokens = [t.strip() for t in os.getenv("BEARER_TOKENS", "").split(",") if t.strip()]
+if tokens:
+    app.add_middleware(BearerTokenMiddleware, verifier=LocalTokenVerifier(tokens))
+```
+
+環境変数 `BEARER_TOKENS=secret-token-1,secret-token-2` でカンマ区切りの複数トークンを設定。
+
+### 2. MCP サーバーから認証付きで呼び出す
+
+```python
+token = os.getenv("MCP_BEARER_TOKEN", "")
+client = HttpxMcpClient(token if token else None)
+
+@server.tool("List all journal entries.")
+def list_entries(limit: int = 20, offset: int = 0) -> str:
+    response = client.get(API_BASE, f"/entries?limit={limit}&offset={offset}")
+    response.raise_for_error()
+    return response.body
+```
+
+`MCP_BEARER_TOKEN=secret-token-1` を MCP サーバーの環境変数に設定。
+`HttpxMcpClient(token)` が `Authorization: Bearer <token>` ヘッダーを自動付与。
+
+### 3. 動作確認
+
+```
+# MCP → 認証付き API → 成功
+create_entry("First Entry", "Hello from MCP!") → {"id":1,...}
+list_entries() → {"items":[{"id":1,...}],...}
+
+# 誤トークン → 401 → raise_for_error() → isError: true
+HTTP 401: {"type":"...unauthorized","detail":"The provided token is invalid or expired."}
+```
+
+---
+
+## Friction Points
+
+### FT11-1: `BearerTokenMiddleware` が `/docs`・`/openapi.json` まで保護する
+
+- **摩擦**: ミドルウェアがすべてのパスに適用されるため、
+  FastAPI の Swagger UI (`/docs`) や OpenAPI スキーマ (`/openapi.json`) にアクセスできなくなる
+  ```
+  GET /docs → 401 Unauthorized
+  GET /openapi.json → 401 Unauthorized
+  ```
+- ロードバランサーの `/health` チェックも同様にブロックされる
+- **現状の回避策**: 開発時は `BEARER_TOKENS=` を空にして認証を無効化
+- **深刻度**: HIGH（開発・運用の両方で問題になる。特にヘルスチェックのブロックは本番障害につながる）
+- **解決策**: `BearerTokenMiddleware(app, verifier=..., exclude_paths=["/docs", "/openapi.json", "/health"])` で除外パスを指定できるようにする
+
+### FT11-2: `MCP_BEARER_TOKEN` 未設定時に分かりにくい 401 エラー
+
+- **摩擦**: MCP サーバー起動時に `MCP_BEARER_TOKEN` が未設定の場合、
+  `HttpxMcpClient(None)` になって認証ヘッダーなしで API を呼ぶ
+- MCP ツール呼び出しが `HTTP 401` で失敗するが、エラーメッセージからトークン未設定が原因と気づきにくい
+  ```
+  McpHttpError: HTTP 401: {"detail":"A valid Bearer token is required."}
+  ```
+- **深刻度**: LOW（エラーメッセージを読めば原因はわかる）
+- **解決策**: `mcp_server.py` でトークン未設定時に起動時警告を出す（フレームワーク対応不要、パターン文書化）
+
+### FT11-3: `LocalTokenVerifier` がカンマ区切り文字列の分割を要求する
+
+- **摩擦**: 複数トークンを環境変数で渡す標準パターンがなく、アプリ側でカンマ分割処理を書く必要がある
+  ```python
+  tokens = [t.strip() for t in os.getenv("BEARER_TOKENS", "").split(",") if t.strip()]
+  ```
+- FT3 でも同様のコードを書いていた（重複パターン）
+- **深刻度**: LOW（数行のコードだが、毎回書く必要がある）
+- **解決策**: `LocalTokenVerifier.from_env("BEARER_TOKENS")` クラスメソッドを追加
+
+---
+
+## Summary
+
+| ID     | 摩擦                                                     | 深刻度 | 解決策                                          |
+|--------|----------------------------------------------------------|--------|-------------------------------------------------|
+| FT11-1 | `BearerTokenMiddleware` が `/docs`・`/health` もブロック | HIGH   | `exclude_paths` 引数を追加                      |
+| FT11-2 | `MCP_BEARER_TOKEN` 未設定時の 401 が原因不明に見える     | LOW    | 起動時警告パターンを文書化                      |
+| FT11-3 | `LocalTokenVerifier` の複数トークン設定にボイラープレート | LOW    | `LocalTokenVerifier.from_env()` クラスメソッド |
+
+**`HttpxMcpClient(bearer_token)` + `raise_for_error()` の組み合わせは期待通りに動作した。**
+認証エラー（401）は `McpHttpError` として raise され、MCP の `isError: true` に正しく変換される。
+
+FT12 候補:
+- **FT11-1 の修正**: `BearerTokenMiddleware` に `exclude_paths` を追加
+- **PostgreSQL アダプター**: `RETURNING` 句が使えるかを検証
+- **SSE トランスポート**: `streamable-http` との差異を確認

{nene2_python-1.3.0 → nene2_python-1.4.0}/docs/how-to/configure-auth.md

@@ -81,6 +81,55 @@ class JwtTokenVerifier:
 
 Pass your verifier directly to `BearerTokenMiddleware`.
 
+## Loading tokens from environment variables
+
+Use `LocalTokenVerifier.from_env()` to avoid writing the split-and-strip boilerplate every time:
+
+```dotenv
+# .env
+BEARER_TOKENS=token-a,token-b,token-c
+```
+
+```python
+from nene2.auth import BearerTokenMiddleware, LocalTokenVerifier
+
+app.add_middleware(
+    BearerTokenMiddleware,
+    verifier=LocalTokenVerifier.from_env("BEARER_TOKENS"),
+)
+```
+
+An unset or empty variable produces an empty allowlist — all requests are denied.
+
+## Excluding paths from authentication
+
+Use `exclude_paths` to bypass auth for health checks and API docs:
+
+```python
+app.add_middleware(
+    BearerTokenMiddleware,
+    verifier=LocalTokenVerifier.from_env("BEARER_TOKENS"),
+    exclude_paths=["/docs", "/openapi.json", "/redoc", "/health"],
+)
+```
+
+`ApiKeyAuthMiddleware` supports the same parameter.
+
+## MCP server — fail fast on missing token
+
+When an MCP server calls a Bearer-protected API via `HttpxMcpClient`, validate the token
+at startup rather than discovering a missing token at call time:
+
+```python
+import os
+from nene2.mcp.http_client import HttpxMcpClient
+
+token = os.getenv("MCP_BEARER_TOKEN")
+if not token:
+    raise RuntimeError("MCP_BEARER_TOKEN is not set — cannot call the authenticated API.")
+client = HttpxMcpClient(token)
+```
+
 ## Custom TokenIssuer (e.g. JWT)
 
 Implement `TokenIssuerProtocol` to issue tokens (e.g. for a login endpoint).

{nene2_python-1.3.0 → nene2_python-1.4.0}/pyproject.toml

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

{nene2_python-1.3.0 → nene2_python-1.4.0}/src/nene2/auth/api_key.py

@@ -17,13 +17,32 @@ _API_KEY_HEADER = "X-Api-Key"
 
 
 class ApiKeyAuthMiddleware(BaseHTTPMiddleware):
-    """Require a valid X-Api-Key header on every request."""
-
-    def __init__(self, app: object, *, verifier: TokenVerifierProtocol) -> None:
+    """Require a valid X-Api-Key header on every request.
+
+    Use ``exclude_paths`` to skip authentication for specific paths such as
+    health-check endpoints or API documentation::
+
+        app.add_middleware(
+            ApiKeyAuthMiddleware,
+            verifier=LocalTokenVerifier(api_keys),
+            exclude_paths=["/docs", "/openapi.json", "/redoc", "/health"],
+        )
+    """
+
+    def __init__(
+        self,
+        app: object,
+        *,
+        verifier: TokenVerifierProtocol,
+        exclude_paths: list[str] | None = None,
+    ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._verifier = verifier
+        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, "")
         try:
             verified = bool(api_key) and self._verifier.verify(api_key)

{nene2_python-1.3.0 → nene2_python-1.4.0}/src/nene2/auth/bearer_token.py

@@ -17,13 +17,32 @@ _WWW_AUTH = 'Bearer realm="api"'
 
 
 class BearerTokenMiddleware(BaseHTTPMiddleware):
-    """Require a valid Bearer token on every request."""
+    """Require a valid Bearer token on every request.
 
-    def __init__(self, app: object, *, verifier: TokenVerifierProtocol) -> None:
+    Use ``exclude_paths`` to skip authentication for specific paths such as
+    health-check endpoints or API documentation::
+
+        app.add_middleware(
+            BearerTokenMiddleware,
+            verifier=LocalTokenVerifier(tokens),
+            exclude_paths=["/docs", "/openapi.json", "/redoc", "/health"],
+        )
+    """
+
+    def __init__(
+        self,
+        app: object,
+        *,
+        verifier: TokenVerifierProtocol,
+        exclude_paths: list[str] | None = None,
+    ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._verifier = verifier
+        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)
         auth = request.headers.get("Authorization", "")
         if not auth.startswith("Bearer "):
             response = problem_details_response(

nene2_python-1.4.0/src/nene2/auth/local_verifier.py

@@ -0,0 +1,36 @@
+"""Local token verifier — compares against a fixed set of allowed tokens.
+
+For development and testing only. In production, implement TokenVerifierProtocol
+against your actual auth backend (database, external IdP, JWT, etc.).
+"""
+
+import os
+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
+
+    @classmethod
+    def from_env(cls, env_var: str, *, separator: str = ",") -> "LocalTokenVerifier":
+        """Create a verifier from a separator-delimited environment variable.
+
+        Example .env::
+
+            BEARER_TOKENS = token - a, token - b, token - c
+
+        Usage::
+
+            verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+
+        An unset or empty variable results in an empty allowlist (all requests denied).
+        """
+        raw = os.getenv(env_var, "")
+        tokens = [t.strip() for t in raw.split(separator) if t.strip()]
+        return cls(tokens)
+
+    def verify(self, token: str) -> bool:
+        return any(secrets.compare_digest(token, allowed) for allowed in self._allowed)

{nene2_python-1.3.0 → nene2_python-1.4.0}/tests/nene2/auth/test_api_key.py

@@ -46,6 +46,27 @@ def test_multiple_allowed_keys() -> None:
     assert client.get("/secret", headers={"X-Api-Key": "key-c"}).status_code == 401
 
 
+def test_exclude_paths_bypasses_auth() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        ApiKeyAuthMiddleware,
+        verifier=LocalTokenVerifier(["key"]),
+        exclude_paths=["/health"],
+    )
+
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    @app.get("/secret")
+    async def secret() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.get("/health").status_code == 200
+    assert client.get("/secret").status_code == 401
+
+
 def test_verifier_raises_token_verification_exception_returns_401() -> None:
     """TokenVerificationException from verifier must return 401, not 500."""
 

{nene2_python-1.3.0 → nene2_python-1.4.0}/tests/nene2/auth/test_bearer_token.py

@@ -58,3 +58,58 @@ def test_local_verifier_constant_time() -> None:
     assert verifier.verify("secret-token") is True
     assert verifier.verify("wrong") is False
     assert verifier.verify("") is False
+
+
+def test_local_verifier_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEST_TOKENS", "tok-a,tok-b, tok-c ")
+    verifier = LocalTokenVerifier.from_env("TEST_TOKENS")
+    assert verifier.verify("tok-a") is True
+    assert verifier.verify("tok-c") is True
+    assert verifier.verify("tok-d") is False
+
+
+def test_local_verifier_from_env_unset(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("TEST_TOKENS", raising=False)
+    verifier = LocalTokenVerifier.from_env("TEST_TOKENS")
+    assert verifier.verify("anything") is False
+
+
+def test_local_verifier_from_env_custom_separator(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("TEST_TOKENS", "tok-a|tok-b")
+    verifier = LocalTokenVerifier.from_env("TEST_TOKENS", separator="|")
+    assert verifier.verify("tok-a") is True
+    assert verifier.verify("tok-b") is True
+
+
+def test_exclude_paths_bypasses_auth() -> None:
+    app = FastAPI()
+    app.add_middleware(
+        BearerTokenMiddleware,
+        verifier=LocalTokenVerifier(["tok"]),
+        exclude_paths=["/health", "/docs"],
+    )
+
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    @app.get("/secret")
+    async def secret() -> JSONResponse:
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    assert client.get("/health").status_code == 200
+    assert client.get("/secret").status_code == 401
+    assert client.get("/secret", headers={"Authorization": "Bearer tok"}).status_code == 200
+
+
+def test_exclude_paths_default_is_empty() -> None:
+    app = FastAPI()
+    app.add_middleware(BearerTokenMiddleware, verifier=LocalTokenVerifier(["tok"]))
+
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    client = TestClient(app)
+    assert client.get("/health").status_code == 401

{nene2_python-1.3.0 → nene2_python-1.4.0}/uv.lock

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

nene2_python-1.3.0/src/nene2/auth/local_verifier.py

@@ -1,17 +0,0 @@
-"""Local token verifier — compares against a fixed set of allowed tokens.
-
-For development and testing only. In production, implement TokenVerifierProtocol
-against your actual auth backend (database, external IdP, JWT, etc.).
-"""
-
-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 verify(self, token: str) -> bool:
-        return any(secrets.compare_digest(token, allowed) for allowed in self._allowed)