nene2-python 1.8.35__tar.gz → 1.8.37__tar.gz

{nene2_python-1.8.35 → nene2_python-1.8.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.35
+Version: 1.8.37
 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
@@ -28,7 +28,6 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: mcp>=1.0
 Requires-Dist: pydantic-settings>=2.6
 Requires-Dist: pydantic>=2.9
-Requires-Dist: pyjwt>=2.12.0
 Requires-Dist: python-multipart>=0.0.12
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: sqlalchemy>=2.0.49

nene2_python-1.8.37/docs/field-trials/2026-05-field-trial-165.md

@@ -0,0 +1,389 @@
+# FT165: secrets モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `secrets` モジュール — 暗号学的安全な乱数・タイミング安全比較・OTP 生成
+**セキュリティ診断**: **あり**（165 % 3 = 0）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `secrets` モジュールを nene2-python フレームワーク上で検証した。
+`secrets` は OS の乱数源（`/dev/urandom` 相当）を使用して暗号学的に安全なトークンを生成するモジュール。
+セキュリティトークン・OTP・API キー生成のベストプラクティスであり、
+`random` モジュールの代替として NIST SP 800-63B が推奨する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft165-secrets/`
+
+### 主要機能
+
+| 関数 | 概要 |
+|---|---|
+| `generate_token_hex(nbytes)` | `secrets.token_hex()` で hex トークン生成、最低 128 bit を保証 |
+| `generate_token_urlsafe(nbytes)` | `secrets.token_urlsafe()` で URL 安全トークン生成 |
+| `generate_token_bytes_b64(nbytes)` | `secrets.token_bytes()` で raw バイト生成（Base64 エンコード返却） |
+| `timing_safe_compare(a, b)` | `hmac.compare_digest()` でタイミング安全比較 |
+| `randbelow_demo(upper)` | `secrets.randbelow()` で範囲内乱数生成 |
+| `generate_otp(length)` | `secrets.choice()` で紛らわしい文字を除いた OTP 生成 |
+| `random_module_usage_check()` | nene2-python ソースで `random` モジュール使用なしを検証 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/secrets/token-hex` | hex トークン生成 |
+| GET | `/secrets/token-urlsafe` | URL 安全トークン生成 |
+| GET | `/secrets/token-bytes` | バイトトークン（Base64）生成 |
+| POST | `/secrets/compare` | タイミング安全比較 |
+| GET | `/secrets/randbelow` | 範囲内乱数 |
+| POST | `/secrets/otp` | OTP 生成 |
+| GET | `/secrets/audit/random-module-check` | セキュリティ自己診断 |
+
+---
+
+## テスト結果
+
+**32 passed（摩擦ゼロ）**
+
+```
+32 passed in 0.87s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `MIN_TOKEN_BYTES = 16` を強制してセキュリティ下限を守る
+
+```python
+MIN_TOKEN_BYTES = 16  # NIST SP 800-63B: 最低 128 bit
+
+def generate_token_hex(nbytes: int = 32) -> TokenResult:
+    safe_nbytes = max(MIN_TOKEN_BYTES, nbytes)
+    return TokenResult(value=secrets.token_hex(safe_nbytes), ...)
+```
+
+呼び出し元が `nbytes=1` を渡しても 128 bit 以上を保証する。
+nene2-python のトークン生成 API はこのパターンを標準にすべき。
+
+### 観察2: `hmac.compare_digest` vs `secrets.compare_digest`
+
+Python 3.12+ では `hmac.compare_digest` と `secrets.compare_digest` はどちらも定時間比較。
+`secrets.compare_digest` は Python 3.14 で追加されたが、3.12 では `hmac.compare_digest` を使う。
+nene2-python の `auth/local_verifier.py` は `secrets.compare_digest` を使っており正しい（3.14 環境）。
+
+### 観察3: OTP のアルファベットから紛らわしい文字を除外
+
+```python
+OTP_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"  # 0/O, 1/I/L を除外
+code = "".join(secrets.choice(OTP_ALPHABET) for _ in range(length))
+```
+
+`0` と `O`、`1` と `I` と `L` はフォントによって区別しにくい。
+人間が読む OTP では除外が必須。`secrets.choice()` は毎回独立した乱数を引くため分布が均等。
+
+### 観察4: `token_hex(n)` の文字列長は `2n`
+
+```python
+secrets.token_hex(32)  # → 64文字の hex 文字列
+```
+
+`n` バイト = `2n` 文字（1 バイト = 2 hex 文字）。
+ドキュメントに書いてあるが初心者が `len(token) == nbytes` と誤解しやすい。
+
+### 観察5: `token_urlsafe(n)` の長さは可変（Base64 パディング依存）
+
+```python
+secrets.token_urlsafe(32)  # → 43文字（32バイトを Base64url でエンコード）
+```
+
+Base64url は 3 バイトごとに 4 文字になるためパディングで長さが変わる。
+DB カラムのサイズ設計時は `len(token_urlsafe(n))` を実測すること。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `auth/local_verifier.py` がすでに `secrets.compare_digest()` を使用：正しい実装
+- `security/webhook.py` が `hmac.compare_digest()` を使用：正しい実装
+- `random` モジュールはソース全体で使用ゼロ：PASS
+- トークン生成ヘルパーを `nene2.security` に追加するとユーザーが安全なデフォルトを使いやすくなる
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+セキュリティモジュールについて「とりあえず動くもの」を求める段階。
+`random.token_hex()` が存在しないことを知らず、`random.random()` でトークンを作ってしまうリスクが高い。
+
+**ドキュメント理解**: `secrets` vs `random` の使い分けがドキュメントにないと区別できない。
+「API キー生成には必ず secrets モジュールを使う」という1文があれば十分。
+
+**事故リスク**: **高**。`random.getrandbits(128)` で作ったトークンは予測可能。
+攻撃者はシードを推測して有効なセッショントークンを列挙できる（実際の攻撃例あり）。
+
+**規約の使いやすさ**: `secrets.token_urlsafe()` のシグネチャは直感的。
+「`n` バイト → `2n` 文字」だけ補足があれば使える。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`uuid.uuid4()` をトークンとして使っているケースが多い（UUID v4 は 122 bit のエントロピーがあるが、
+ライブラリによっては擬似乱数源を使う）。
+
+**コピペ可能性**: `secrets.token_urlsafe(32)` のワンライナーはコピペしやすい。
+サンプルに「これが正しいやり方」と明示されていれば従う。
+
+**拡張時の罠**: タイミング攻撃が理解されていない。
+`if user_token == db_token:` という `==` 比較を「動いているから OK」と思いがち。
+`hmac.compare_digest` が必要な理由を 1 行コメントで説明する価値がある。
+
+**セキュリティ的な事故リスク**: **高**。タイミング攻撃によるトークン列挙は実際の攻撃手法。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+Node.js の `crypto.randomBytes()` / `crypto.timingSafeEqual()` と同等の概念を理解している。
+
+**Python 固有概念の学習コスト**: `hmac.compare_digest` が `secrets.compare_digest` と違うモジュールにあることが混乱点。
+Python 3.14+ では `secrets.compare_digest` も使える。
+
+**事故リスク**: 低。暗号トークンの概念は既知。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `get_random_string()` / `constant_time_compare()` との対応がわかれば即座に使える。
+
+**他フレームワークとの差異**: Django は `django.utils.crypto.constant_time_compare()` でラップ済み。
+nene2-python は `hmac.compare_digest()` を直接使う必要がある（より透明性が高い）。
+
+**本番投入可能性**: 問題なし。`secrets` モジュールは stdlib で外部依存なし。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] トークン生成に `random` / `uuid.uuid4()` ではなく `secrets` を使っているか
+- [ ] トークン比較に `==` ではなく `hmac.compare_digest` / `secrets.compare_digest` を使っているか
+- [ ] `nbytes` が最低 16 以上（128 bit）か
+- [ ] OTP のアルファベットに紛らわしい文字（0/O/1/I/L）が含まれていないか
+- [ ] `token_hex(n)` の長さが `n` ではなく `2n` 文字であることをカラムサイズ設計に反映しているか
+
+**チームでの安全なパターン**: `nene2.security.generate_token()` ヘルパーに最低ビット強度を組み込むことで、
+チームメンバーが誤って短いトークンを生成するリスクを排除できる。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高（`secrets` モジュール使用はCLAUDE.mdで必須化済み）
+
+**「初心者でも安全な API」達成度**: 中
+- `nene2.security` に最低 128 bit を保証するトークン生成ヘルパーがあれば「高」になる
+- 現状は「`secrets` を使え」というポリシーだけで、安全なデフォルトが提供されていない
+
+**設計上の負債**: `nene2.security` に `generate_api_key()`、`generate_session_token()` などの
+安全なデフォルトを持つ高レベルヘルパーが未実装。
+
+**Follow-up Issue 候補**: `feat: nene2.security に generate_token() ヘルパーを追加（最低 128 bit 保証）`
+
+---
+
+## セキュリティ診断（FT165 — 165 % 3 = 0）
+
+> **診断方針**: Django・FastAPI・SQLAlchemy 本体でも CVE が報告されてきたレベルの
+> 攻撃ベクターを対象とする。「動いているから安全」は不正解。
+
+### 1. OWASP API Security Top 10 (2023)
+
+#### API1: BOLA / IDOR
+- ユーザー所有リソースがないため対象外（トークン生成 API）
+- **結果**: ✅ 対象外
+
+#### API2: 認証の破損
+- [ ] `auth/local_verifier.py:36` で `secrets.compare_digest()` 使用確認 → **✅ PASS**
+- [ ] 保護エンドポイント: FT165 アプリは認証なしの公開 API のため対象外
+- **結果**: ✅
+
+#### API3: Mass Assignment
+- 実測: `POST /secrets/compare` に `{"a":"x","b":"y","is_admin":true}` → 200、レスポンスに `is_admin` なし
+- Pydantic が extra フィールドを無視（デフォルト動作）
+- **結果**: ✅ PASS
+
+#### API4: 無制限リソース消費
+- 実測: `a="x"*513` → 422（`max_length=512` で拒否）
+- 実測: `upper=1_000_001` → 422（`le=1_000_000` で拒否）
+- `ThrottleMiddleware`: FT165 アプリは未設定（本番では必須）
+- **結果**: ✅ バリデーション境界は機能。スロットリングは本番設定が必要
+
+#### API5: 機能レベルの認可不備
+- FT165 は認証不要の公開 API のため対象外
+- **結果**: ✅ 対象外
+
+#### API6: SSRF
+- URL を受け取るフィールドなし
+- **結果**: ✅ 対象外
+
+#### API7: セキュリティの設定ミス
+- 実測: `X-Request-Id`, `X-Content-Type-Options`, `X-Frame-Options` → ✅ 全レスポンスに付与
+- 実測: 422 エラーレスポンスにスタックトレース含まれず → ✅
+- CORS ワイルドカード: `grep allow_origins="*"` → ✅ PASS
+- **結果**: ✅
+
+#### API8〜10
+- バージョン管理・デバッグエンドポイント・外部 API 消費: FT165 アプリでは対象なし
+- **結果**: ✅ 対象外
+
+---
+
+### 2. インジェクション攻撃
+
+#### SQL インジェクション
+- `grep -rn 'f".*SELECT|INSERT|UPDATE|DELETE'` → **PASS（0 件）**
+- FT165 アプリに DB 操作なし
+- **結果**: ✅
+
+#### コマンドインジェクション
+- `grep -rn "shell=True\|os\.system"` → **PASS（0 件）**
+- `random_module_usage_check()` 内の `subprocess.run()` は固定引数のみ（ユーザー入力なし）
+- **結果**: ✅
+
+#### パストラバーサル
+- FT165 アプリにファイル操作なし
+- **結果**: ✅ 対象外
+
+#### SSTI
+- テンプレートエンジン使用なし
+- **結果**: ✅ 対象外
+
+---
+
+### 3. 認証・認可
+
+- `random` モジュール使用: **PASS（0 件）**
+- `secrets.compare_digest` / `hmac.compare_digest` の使用: **✅ 両方で正しく実装済み**
+  - `auth/local_verifier.py:36`: `secrets.compare_digest(token, allowed)`
+  - `security/webhook.py:29`: `hmac.compare_digest(expected, signature)`
+- `SecretStr` 使用箇所: 2 件（設定クラス内）
+- **結果**: ✅ 全 PASS
+
+---
+
+### 4. 入力バリデーション
+
+- `CompareBody.a/b`: `max_length=512` → 実測で 413 文字超で 422 ✅
+- `nbytes`: `ge=1, le=64` で境界チェック ✅
+- `upper`: `ge=2, le=1_000_000` で境界チェック ✅
+- タイプエラー: `nbytes="bad"` → 422（スタックトレースなし）✅
+- **結果**: ✅
+
+---
+
+### 5. 情報漏洩
+
+- 422 エラーに `traceback` / `File "` 含まれず ✅
+- `SecretStr` でパスワード系フィールドを保護（2 箇所）✅
+- セキュリティヘッダー全レスポンスに付与 ✅
+- **結果**: ✅
+
+---
+
+### 6. Python / FastAPI 固有の攻撃ベクター
+
+#### ReDoS
+- `middleware/request_id.py` の UUID 正規表現: `^[0-9a-f]{8}-...-[0-9a-f]{12}$`
+- 実測（悪意ある入力 `"a"*40+"!"`）: **0.00ms** — バックトラッキング爆発なし ✅
+- **結果**: ✅
+
+#### pickle / yaml / eval
+- `grep eval\|exec\|pickle.loads\|yaml.load` → **PASS（0 件）** ✅
+- **結果**: ✅
+
+#### 非同期レースコンディション・型強制攻撃
+- FT165 はステートレスな計算 API のため共有状態なし ✅
+- Pydantic: `int` フィールドに文字列 `"bad"` → 422（型強制失敗でエラー返却）✅
+- **結果**: ✅
+
+---
+
+### 7. 依存関係の脆弱性スキャン
+
+```
+uv run pip-audit
+```
+
+**結果**:
+
+| Package | Version | ID | Fix Versions |
+|---|---|---|---|
+| pyjwt | 2.12.1 | PYSEC-2025-183 | （未記載） |
+
+**CRITICAL: 1 件**
+
+**詳細分析**:
+- PyJWT 2.12.1 は `PYSEC-2025-183` の影響を受ける
+- `pip-audit` の Fix Versions 欄が空 → 修正版未リリースの可能性
+- **実際の影響**: nene2-python のソースコード全体を検索した結果、`import jwt` / `import pyjwt` が実コードに存在しない（コメントのみ）
+- PyJWT は `pyproject.toml` に直接依存として宣言されていたが **デッド依存** → 本 FT で削除済み
+- **推移的依存として残存**: `mcp>=1.0` パッケージが `pyjwt[crypto]` を推移的依存として使用しているため、pip-audit では引き続き検出される
+
+**対応方針**:
+1. `pyproject.toml` からの直接依存宣言: **本 FT で削除済み** (`uv remove pyjwt`)
+2. 推移的依存（mcp 経由）: mcp 側の修正を待つ。Fix Versions が空のため修正版未リリース。Issue で追跡する。
+3. nene2-python のコードが PyJWT を直接使わないため、実際の攻撃面はゼロ。
+
+---
+
+### 診断サマリー
+
+| カテゴリ | 結果 | 最重要発見 |
+|---|---|---|
+| OWASP API Security Top 10 | ✅ | スロットリング未設定（本番要対応） |
+| SQL インジェクション | ✅ | — |
+| コマンドインジェクション | ✅ | — |
+| パストラバーサル | ✅ | — |
+| SSTI | ✅ | — |
+| 認証・認可 | ✅ | compare_digest 正しく実装 |
+| 入力バリデーション | ✅ | — |
+| 情報漏洩 | ✅ | — |
+| ReDoS | ✅ | 0ms — 安全 |
+| pickle / yaml / eval | ✅ | — |
+| 非同期レースコンディション | ✅ | — |
+| 型強制攻撃 | ✅ | — |
+| 依存関係 CVE | ❌ | **PyJWT 2.12.1 PYSEC-2025-183（デッド依存）** |
+
+**総合評価**: **条件付き合格**（PyJWT CVE を次 PR で対処すること）
+
+**発見した脆弱性**: 1 件（CRITICAL: 1 — PyJWT デッド依存 CVE）
+
+**新規セキュリティ Issue**: PyJWT 依存削除または更新
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 高 | `fix: pyproject.toml から未使用の pyjwt 直接依存を削除（PYSEC-2025-183）` ← **本 FT で対処済み** | security |
+| 高 | `track: mcp の推移的依存 pyjwt PYSEC-2025-183 修正版リリース待ち` | security |
+| 中 | `feat: nene2.security に generate_token() ヘルパーを追加（最低 128 bit 保証）` | feat |
+| 低 | `docs: secrets vs random の使い分けを how-to に追加` | docs |
+
+---
+
+## まとめ
+
+`secrets` モジュールは暗号学的安全なトークン生成・タイミング安全比較の標準手段。
+32 テスト全通過、摩擦ゼロで実装完了。
+
+セキュリティ診断では nene2-python のソースコード全体を横断的に確認した。
+`compare_digest` の正しい使用・`random` モジュール不使用・型バリデーション・セキュリティヘッダーはすべて合格。
+**唯一の発見: PyJWT 2.12.1 のデッド依存 CVE (PYSEC-2025-183)**。
+実際に使われていない依存が CVE を持つことはそれ自体がリスクのため、即時削除 PR を作成する。

nene2_python-1.8.37/docs/field-trials/2026-05-field-trial-166.md

@@ -0,0 +1,246 @@
+# FT166: functools モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `functools` モジュール — `lru_cache`・`cached_property`・`partial`・`wraps`・`reduce`・`cache`
+**セキュリティ診断**: なし（166 % 3 = 1）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `functools` モジュールを nene2-python フレームワーク上で検証した。
+`functools` は高階関数・デコレーター・メモ化のユーティリティを提供し、
+nene2-python の DI パターン・レスポンスキャッシュ・ミドルウェア実装に直結する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft166-functools/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `fibonacci(n)` | `@lru_cache(maxsize=128)` でメモ化された再帰 fibonacci |
+| `expensive_computation(key)` | `@lru_cache(maxsize=32)` で文字列キーのキャッシュ |
+| `HeavyComputer` | `@cached_property` で total / average を遅延計算・キャッシュ |
+| `double / triple` | `functools.partial` で multiply の引数を固定 |
+| `greet_hello / greet_hi` | `partial` でテンプレートと記号を固定したあいさつ生成 |
+| `timing_decorator` | `@functools.wraps` でデコレーターが元の関数名・docstring を保持 |
+| `product_reduce(numbers)` | `functools.reduce` で積を計算 |
+| `flatten_reduce(nested)` | `reduce` でネストしたリストをフラット化 |
+| `collatz_steps(n)` | `@functools.cache`（unbounded）でコラッツ数列ステップ数をメモ化 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/functools/fibonacci` | lru_cache 付き fibonacci（キャッシュ統計返却） |
+| GET | `/functools/lru-cache` | 任意キーのキャッシュ統計デモ |
+| GET | `/functools/cached-property` | HeavyComputer の計算回数デモ |
+| GET | `/functools/partial` | double / triple / greet デモ |
+| GET | `/functools/wraps` | slow_add の __name__ 保持確認 |
+| POST | `/functools/reduce-product` | 整数リストの積 |
+| POST | `/functools/reduce-flatten` | ネストリストのフラット化 |
+| GET | `/functools/cache-collatz` | unbounded cache でコラッツ数列 |
+
+---
+
+## テスト結果
+
+**34 passed（摩擦ゼロ）**
+
+```
+34 passed in 0.83s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `@lru_cache` はグローバル状態 — テスト間でキャッシュを `clear` する必要がある
+
+```python
+@pytest.fixture(autouse=True)
+def clear_caches() -> None:
+    fibonacci.cache_clear()
+    expensive_computation.cache_clear()
+```
+
+`@lru_cache` の対象関数はプロセス共有のキャッシュを持つ。
+テスト間でキャッシュが汚染されるため `autouse=True` で毎回クリアする必要がある。
+nene2-python でキャッシュを使う UseCase は `cache_clear()` を lifespan の shutdown で呼ぶか、
+または `@lru_cache` をクラスメソッドに適用してインスタンス単位でスコープを制御する。
+
+### 観察2: `@cached_property` はインスタンス単位 — `lru_cache` との使い分け
+
+```python
+class HeavyComputer:
+    @functools.cached_property
+    def total(self) -> int:
+        self.compute_count += 1
+        return sum(self._data)
+```
+
+`@cached_property` はインスタンスの `__dict__` に値を保存する。
+同じインスタンスで 2 回目のアクセスは計算なし。新しいインスタンスは再計算。
+`@lru_cache` はプロセス全体で共有・引数でキー管理、`@cached_property` はインスタンスで管理。
+nene2-python での使い分け:
+- UseCase / Repository インスタンスの設定値計算 → `@cached_property`
+- 引数ベースの重い計算（ページネーション計算など）→ `@lru_cache`
+
+### 観察3: `@functools.cache` = `@lru_cache(maxsize=None)` でメモリ無制限
+
+```python
+@functools.cache  # Python 3.9+ / unbounded
+def collatz_steps(n: int) -> int: ...
+```
+
+`@cache` は `@lru_cache(maxsize=None)` の略記で、キャッシュサイズ制限なし。
+再帰的な数学関数に適しているが、引数の値域が大きい場合はメモリ枯渇に注意。
+nene2-python での用途: 設定値の解析結果など、引数の種類が少ない場合に使う。
+
+### 観察4: `functools.partial` で DI 設定をカリー化できる
+
+```python
+double = functools.partial(multiply, y=2)
+greet_hello = functools.partial(make_greeting, "Hello")
+```
+
+FastAPI の `Depends` と組み合わせる場合、`partial` でリポジトリに設定を注入できる:
+```python
+get_repo = functools.partial(NoteRepository, db_url=settings.db_url)
+Depends(get_repo)
+```
+ただし `Depends` に渡す関数はシグネチャが重要なため、`partial` が残す引数を確認すること。
+
+### 観察5: `@functools.wraps` なしのデコレーターは `__name__` を上書きする
+
+```python
+def timing_decorator(func):
+    # @functools.wraps(func) がないと:
+    def wrapper(*args, **kwargs): ...
+    return wrapper  # → slow_add.__name__ == "wrapper" になる
+
+def timing_decorator(func):
+    @functools.wraps(func)  # ← これがないと OpenAPI ルート名が壊れる
+    def wrapper(*args, **kwargs): ...
+    return wrapper
+```
+
+FastAPI はルート関数の `__name__` を operationId に使う。
+カスタムミドルウェア・デコレーターに `@functools.wraps` がないと OpenAPI スキーマが壊れる。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `@lru_cache` は `TtlCache`（FT100 で追加済み）と役割が異なる（TTL なし vs TTL あり）
+- `@cached_property` は Repository の設定パース結果のキャッシュに最適
+- `@functools.wraps` は nene2-python の `BearerTokenMiddleware` 等のデコレーターで使用が推奨される
+- `functools.reduce` は UseCase の集計ロジックに使えるが、`sum()` / リスト内包表記の方が可読性が高い場合が多い
+- `@functools.cache` は設定値の解析・静的ルックアップに適している
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`@lru_cache` は「デコレーターをつけるとキャッシュされる」という概念は分かりやすいが、
+`cache_clear()` が必要なことや、グローバル共有であることは見落としやすい。
+
+**ドキュメント理解**: `@lru_cache` のサンプルはフィボナッチが定番だが、
+「Web API の UseCase でいつ使うか」の例がないと「難しそうなやつ」で止まる。
+
+**事故リスク**: 中。`@lru_cache` をテストで使うときにキャッシュをクリアし忘れ、
+他のテストのキャッシュが漏れ込んでテストが通ったり失敗したりするフレーキーなテストが生まれる。
+
+**規約の使いやすさ**: `@functools.wraps` の必要性は理解しにくい。
+「デコレーターを作るときは必ず `@functools.wraps` をつける」という規則を覚えれば十分。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`functools` は名前を知っていても使いこなせていないことが多い。
+`reduce` は「forループで書いた方が分かる」と言って使わない傾向がある。
+
+**コピペ可能性**: `@lru_cache(maxsize=128)` と `@functools.wraps(func)` はそのままコピペできる。
+
+**拡張時の罠**: `@lru_cache` の引数が変わったときにキャッシュが古い値を返し続ける。
+引数の型が mutable（`list`, `dict`）だと `TypeError: unhashable type` が発生することに気づかない。
+
+**セキュリティ的な事故リスク**: 低。ただし `@lru_cache` に認証情報を含む引数を渡すと
+別ユーザーのキャッシュが混入するリスクがある（BOLA の一形態）。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+`useMemo` / `useCallback` と `@lru_cache` / `@cached_property` は概念が近い。
+「同じ入力なら再計算しない」という理解はすでにある。
+
+**Python 固有概念の学習コスト**: `partial` は JS の `bind` や `curry` に近い概念。
+`reduce` は `Array.prototype.reduce` と同じ。TypeScript ユーザーには直感的。
+
+**事故リスク**: 低。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `@method_decorator` / `cache_page` との差異を理解している。
+`@functools.wraps` は既知。`@lru_cache` の eviction ポリシー（LRU）を正確に理解している。
+
+**他フレームワークとの差異**: Django は `cache.get/set` で明示的にキャッシュを管理する。
+nene2-python で `@lru_cache` を使う場合、TTL がないことを意識する必要がある。
+TTL が必要なら FT100 で追加した `TtlCache` を使う。
+
+**本番投入可能性**: 問題なし。ただしキャッシュキーのサイズとメモリ消費量の設計が必要。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] `@lru_cache` / `@cache` の引数に mutable 型（list, dict）が渡されていないか（`TypeError` になる）
+- [ ] `@lru_cache` をリクエストスコープで使っていないか（プロセス共有で期待外の値が返る）
+- [ ] `@lru_cache` に認証情報・ユーザーIDが引数に含まれる場合、BOLA にならないか
+- [ ] デコレーターに `@functools.wraps` がついているか（OpenAPI operationId の破損防止）
+- [ ] `@cache`（unbounded）を使う場合、引数の値域が有限か（メモリリーク防止）
+
+**チームでの安全なパターン**: キャッシュが必要な UseCase は `cache_clear()` を公開メソッドとして持ち、
+lifespan の shutdown / テストの teardown で明示的にクリアする規約を設ける。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 中
+- `@lru_cache` のキャッシュ汚染リスク（テスト・BOLA）をドキュメントが説明していない
+- `@functools.wraps` の必要性が CLAUDE.md に明記されていない（FastAPI との相性問題）
+
+**設計上の負債・ドキュメント不足**:
+- nene2-python のカスタムデコレーター作成時の `@functools.wraps` 使用がポリシー化されていない
+- `@lru_cache` の「リクエストスコープ不可・認証情報を引数に含めない」ルールが未文書
+
+**Follow-up Issue 候補**: `docs: functools.wraps をカスタムデコレーター規約に追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: @functools.wraps をデコレーター作成規約として CLAUDE.md に追加` | docs |
+| 低 | `docs: @lru_cache のリクエストスコープ不可・認証情報禁止をキャッシュ how-to に記載` | docs |
+
+---
+
+## まとめ
+
+`functools` は nene2-python の DI・キャッシュ・デコレーター実装に広く関連するモジュール。
+34 テスト全通過、摩擦ゼロ。
+`@cached_property` がインスタンス単位、`@lru_cache` がプロセス単位という使い分けが重要。
+`@functools.wraps` なしのデコレーターは FastAPI の operationId を破壊するため、
+カスタムデコレーター規約への追記が推奨される。

{nene2_python-1.8.35 → nene2_python-1.8.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.35"
+version = "1.8.37"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}
@@ -32,7 +32,6 @@ dependencies = [
     "mcp>=1.0",
     "pyyaml>=6.0",
     "httpx>=0.27",
-    "pyjwt>=2.12.0",
 ]
 
 [project.urls]