nene2-python 1.8.48__tar.gz → 1.8.49__tar.gz

{nene2_python-1.8.48 → nene2_python-1.8.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.48
+Version: 1.8.49
 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.49/docs/field-trials/2026-05-field-trial-178.md

@@ -0,0 +1,242 @@
+# FT178: base64 モジュール
+
+**日付**: 2026-05-21
+**テーマ**: エンコード・デコード・URL セーフ変換・データ URI・HTTP Basic Auth パース
+**セキュリティ診断**: なし（178 % 3 = 1）
+
+---
+
+## 概要
+
+Web API で頻繁に使う `base64` モジュールを検証する。
+標準エンコーディングと URL セーフ変換の違い、パディング扱い、データ URI 生成、
+HTTP Basic Auth ヘッダーのパースまで網羅し、落とし穴となる箇所を洗い出す。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft178-base64/`
+
+### 主要機能
+
+| 関数 | 概要 |
+|---|---|
+| `encode_standard(data)` | 標準 base64 エンコード（RFC 4648 §4） |
+| `decode_standard(s)` | 標準 base64 デコード（`validate=True` で厳格検証） |
+| `encode_url_safe(data)` | URL セーフ base64（パディングなし） |
+| `decode_url_safe(s)` | URL セーフ base64 デコード（パディング自動補完 + 文字セット検証） |
+| `encode_text(text)` | UTF-8 テキスト → base64 |
+| `decode_text(s)` | base64 → UTF-8 テキスト（非 UTF-8 は `None`） |
+| `is_valid_base64(s)` | 長さ・文字セット・パディングを検証 |
+| `is_valid_url_safe_base64(s)` | URL セーフ文字セット検証 |
+| `make_data_uri(content, mime_type)` | RFC 2397 データ URI 生成 |
+| `parse_data_uri(uri)` | データ URI → `(mime_type, bytes)` |
+| `encode_basic_auth(username, password)` | HTTP Basic Auth ヘッダー値生成 |
+| `parse_basic_auth(header)` | Authorization ヘッダー → `(username, password)` |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/encode` | 標準 base64 エンコード |
+| POST | `/decode` | 標準 base64 デコード |
+| POST | `/encode/url-safe` | URL セーフ base64 エンコード |
+| POST | `/decode/url-safe` | URL セーフ base64 デコード |
+| POST | `/encode/text` | テキスト → base64 |
+| POST | `/decode/text` | base64 → テキスト |
+| POST | `/data-uri/encode` | データ URI 生成 |
+| POST | `/data-uri/parse` | データ URI 解析 |
+| POST | `/auth/basic/encode` | Basic Auth ヘッダー生成 |
+| POST | `/auth/basic/parse` | Basic Auth ヘッダー解析 |
+
+---
+
+## テスト結果
+
+**58 passed**（初回 1 失敗 → 修正後 58 全通過）
+
+```
+58 passed in 0.43s
+```
+
+mypy: Success / ruff: All checks passed / pip-audit: PYSEC-2025-183（継続監視）
+
+---
+
+## 摩擦ポイント
+
+### F-1: `urlsafe_b64decode` が不正文字をサイレントに無視する（深刻度: 高）
+
+**事象**: `decode_url_safe("!!!invalid!!!")` が `None` を返さず `b"\x8a{\xda\x96'"` を返した。
+
+**原因**: `base64.urlsafe_b64decode()` は RFC 4648 の「ignore non-alphabet characters」モードで動作し、
+`!` などの不正文字を黙って無視してデコードを続ける。
+一方、標準の `b64decode(s, validate=True)` は不正文字で `binascii.Error` を raise する。
+
+**対応**: `urlsafe_b64decode` の前に文字セット正規表現で事前バリデーション：
+```python
+_URL_SAFE_CHARS_RE = re.compile(r"^[A-Za-z0-9_\-=]*$")
+
+def decode_url_safe(s: str) -> bytes | None:
+    stripped = s.rstrip("=")
+    if not stripped or not _URL_SAFE_CHARS_RE.match(stripped):
+        return None
+    ...
+```
+
+**ライブラリ設計上の問題**: `urlsafe_b64decode` に `validate=True` パラメータが存在しない（`b64decode` にはある）。
+URL セーフ版は自前バリデーションが必要という非対称な API 設計。
+
+---
+
+## 観察点
+
+### 観察1: 標準 base64 vs URL セーフ — `validate=True` の非対称性
+
+```python
+# 標準版: validate パラメータがある
+base64.b64decode("not!!!valid", validate=True)  # → binascii.Error
+
+# URL セーフ版: validate パラメータがない
+base64.urlsafe_b64decode("not!!!valid")  # → サイレントに無視してデコード
+```
+
+JWT トークンや OAuth コードは URL セーフ base64 を使う。
+`validate=True` に相当するガードを自前で実装しないと、
+不正トークンを誤って「有効」として処理する脆弱性になりうる。
+
+### 観察2: パディング補完の必要性
+
+RFC 4648 §5 では URL セーフ base64 のパディング（`=`）は省略可能とされており、
+JWT の `alg`・`typ` フィールドなど実際のトークンはパディングなしで渡ってくる。
+
+```python
+# パディングなし JWT ヘッダーを補完してデコード
+stripped = s.rstrip("=")
+padding = 4 - len(stripped) % 4
+if padding != 4:
+    s = stripped + "=" * padding
+```
+
+`padding != 4` の条件で「すでに 4 の倍数の場合はパディングを追加しない」ことも重要。
+
+### 観察3: `partition(":")` で パスワード中のコロン対応
+
+```python
+username, _, password = text.partition(":")  # partition は最初の : で分割
+```
+
+`split(":", 1)` でも同じだが `partition` の方が意図が明示的で、
+`a:b:c:d` → `("a", ":", "b:c:d")` の分解が 1 行で書ける。
+
+### 観察4: データ URI の MIME タイプ検証
+
+```python
+re.match(r"^[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_.+]*$", mime_type)
+```
+
+`image/png`・`application/octet-stream`・`text/plain; charset=utf-8` のような MIME タイプは正規表現で検証。
+`javascript:`・`vbscript:` などの XSS ペイロードをデータ URI に埋め込む試みをブロックできる。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `encode_basic_auth` / `parse_basic_auth` は `ApiKeyAuthMiddleware` の拡張として組み込み可能
+- `make_data_uri` はファイルアップロード API のレスポンス形式として使える
+- Pydantic `max_length` フィールドで全エンドポイントの DoS 対策済み
+- `APIRouter` + `create_app()` パターン（FT177 摩擦 F-1 の対応）を最初から適用
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+画像アップロード API でクライアントから base64 エンコードされたデータを受け取る実装をしている。
+
+**ドキュメント理解**: `b64encode` / `b64decode` のペアは分かりやすい。
+URL セーフ版との違い（`+/` vs `-_`、パディング省略）はドキュメントに書いてないと気づきにくい。  
+**事故リスク**: 中。標準版と URL セーフ版を混在させると復号に失敗し、バイナリ化けとして現れる。
+エラーより「壊れたデータ」として扱われるため気づきにくい。  
+**規約の使いやすさ**: `encode_standard(data)` が `str` を返し、`decode_standard(s)` が `bytes | None` を返すのは直感的。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+JWT パースのコードを既存プロジェクトからコピーしており、URL セーフ base64 を使っている。
+
+**コピペ可能性**: `decode_url_safe` の自前バリデーションが必要な点はコメントがないと気づかない。
+`urlsafe_b64decode` を直接使うと F-1 の罠にはまる。  
+**拡張時の罠**: パディング補完のコードを「なんか動いてるから削ってもいいかな」と消すと壊れる。
+なぜ必要かのコメントが欲しい。  
+**セキュリティ的な事故リスク**: 高。JWT 検証で `urlsafe_b64decode` を `validate=True` なしで使うと、
+改ざんトークンが「デコード成功」として扱われる可能性がある。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+TypeScript の `atob()` / `btoa()` に慣れており、Python で同じことをしようとしている。
+
+**エラーレスポンスの質**: 400 Bad Request に具体的なメッセージ（"Invalid base64 input" 等）が返るのは良い。
+クライアント側でデバッグしやすい。  
+**Python 固有概念の学習コスト**: `bytes.hex()` / `bytes.fromhex()` の往復はTS では意識しない変換。
+`atob()` は文字列を返すが `b64decode` は `bytes` を返す差異に戸惑う可能性。  
+**事故リスク**: 低。HTTP 境界での Pydantic バリデーションが充実。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+JWT ライブラリの内部実装を理解しており、raw base64 操作をすることもある。
+
+**他フレームワークとの差異**: Django の `base64.urlsafe_b64decode` 直接利用パターンと同じ罠（F-1）が
+nene2-python でも起きる。フレームワーク側での救済ではなく実装者が知識として持つ必要がある。  
+**nene2-python の薄さへの評価**: base64 は stdlib を薄くラップするだけが適切。
+`decode_url_safe` のバリデーション付きラッパーは価値あるユーティリティ。  
+**本番投入可能性**: Basic Auth のパースは `parse_basic_auth` 一本で安全に使える設計が好評価。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [x] `urlsafe_b64decode` を自前バリデーションなしで使っていないか（F-1 の罠）
+- [x] パスワードが base64 エンコードのみで「保護されている」と勘違いしていないか
+  （base64 は暗号化ではなくエンコード）
+- [x] Basic Auth をデコードして得たパスワードをそのまま平文比較していないか
+  （`hmac.compare_digest` が必要）
+
+**チームでの安全な共有パターン**: `decode_url_safe` に自前バリデーションを含めたラッパーを
+ユーティリティとして共有すると、チーム全員が安全に使える。  
+**ツール追加の必要性**: `ruff` に base64 固有のルールはなし。コードレビューで担保。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 中  
+— F-1（`urlsafe_b64decode` の無バリデーション問題）は初心者が直接 `base64.urlsafe_b64decode` を使うと再発する。
+`decode_url_safe` ラッパーを使う運用を周知する必要がある。  
+**設計上の負債**: `validate=True` が URL セーフ版に存在しないのは Python stdlib の設計問題。
+ユーザー向けに警告コメントを `decode_url_safe` に追記する価値がある。  
+**Follow-up Issue 候補**: なし（現状の実装で十分）
+
+---
+
+## Follow-up Issues
+
+今回の FT では実装上の重大な摩擦はなし（F-1 は実装内で解消済み）。
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 低 | `decode_url_safe` に「`urlsafe_b64decode` は validate=True がないため自前バリデーションが必要」コメントを追記 | docs |
+
+---
+
+## まとめ
+
+FT178 では `base64` モジュールを中心に、Web API でよく使うエンコード操作を実装した。
+58 テストが全通過し、mypy/ruff も問題なし。
+
+最大の発見は F-1: `base64.urlsafe_b64decode` に `validate=True` がなくサイレントに不正入力を処理してしまう問題。
+JWT・OAuth コード等を URL セーフ base64 で扱うコードが多い中、この挙動は高リスクな落とし穴。
+文字セット正規表現による事前バリデーションで対応済み。
+
+APIRouter パターン（FT177 F-1 からの改善）を最初から適用し、テストが一発で通過した。
+
+v1.8.49 としてリリース。

nene2_python-1.8.49/docs/field-trials/INDEX.md

@@ -0,0 +1,229 @@
+# Field Trial INDEX
+
+フィールドトライアル一覧。テーマ・カテゴリ・診断種別から検索する用途を想定。
+
+**凡例**:
+- 🔒 セキュリティ診断実施（FT番号 % 3 = 0）
+- 🔍 クラッカーペンテスト実施（FT172, 176, 180…）
+- 列 "Follow-up" に関連 GitHub Issue 番号を記載
+
+---
+
+## カテゴリ1: 初期統合検証 (FT1〜FT18)
+
+| FT# | テーマ | 診断 | Follow-up |
+|-----|--------|------|-----------|
+| [FT1](2026-05-field-trial-1.md) | lunchlog — git+ インストール・新規プロジェクト構築 | | |
+| [FT2](2026-05-field-trial-2.md) | bookshelf — SQLite 永続化リポジトリ DX | | |
+| [FT3](2026-05-field-trial-3.md) | tasklist — Bearer Token 認証 + MCP サーバー | 🔒 | |
+| [FT4](2026-05-field-trial-4.md) | snippets — SQLite 共有 MCP・ApiKey 認証・CORS | | |
+| [FT5](2026-05-field-trial-5.md) | wallet — transactional() DX | | |
+| [FT6](2026-05-field-trial-6.md) | weather — AsyncUseCaseProtocol DX | 🔒 | |
+| [FT7](2026-05-field-trial-7.md) | bookmark — PyPI publish フロー | | |
+| [FT8](2026-05-field-trial-8.md) | blog — 親子リソース (Nested REST) + datetime | | |
+| [FT9](2026-05-field-trial-9.md) | recipe — HttpxMcpClient + streamable-http | 🔒 | |
+| [FT10](2026-05-field-trial-10.md) | inventory — MySQL アダプター | | |
+| [FT11](2026-05-field-trial-11.md) | journal — BearerTokenMiddleware + HttpxMcpClient | | |
+| [FT12](2026-05-field-trial-12.md) | ThrottleMiddleware + RequestSizeLimitMiddleware | 🔒 | |
+| [FT13](2026-05-field-trial-13.md) | ValidationException 実運用 | | |
+| [FT14](2026-05-field-trial-14.md) | AsyncUseCaseProtocol 実運用 | | |
+| [FT15](2026-05-field-trial-15.md) | SecurityHeadersMiddleware 実運用 | 🔒 | |
+| [FT16](2026-05-field-trial-16.md) | transactional(callback) パターン | | |
+| [FT17](2026-05-field-trial-17.md) | 複数ドメイン連携 | | |
+| [FT18](2026-05-field-trial-18.md) | RequestLoggingMiddleware 実運用 | 🔒 | |
+
+---
+
+## カテゴリ2: フレームワーク実運用検証 (FT19〜FT80)
+
+| FT# | テーマ | 診断 | Follow-up |
+|-----|--------|------|-----------|
+| [FT19](2026-05-field-trial-19.md) | problem_details_response() RFC 9457 | | |
+| [FT20](2026-05-field-trial-20.md) | ThrottleMiddleware 実運用 | | |
+| [FT21](2026-05-field-trial-21.md) | DomainExceptionHandler | 🔒 | |
+| [FT22](2026-05-field-trial-22.md) | HealthCheckProtocol | | |
+| [FT23](2026-05-field-trial-23.md) | RequestSizeLimitMiddleware | | |
+| [FT24](2026-05-field-trial-24.md) | AppSettings | 🔒 | |
+| [FT25](2026-05-field-trial-25.md) | RequestIdMiddleware | | |
+| [FT26](2026-05-field-trial-26.md) | nene2.log structlog 統合 | | |
+| [FT27](2026-05-field-trial-27.md) | ThrottleMiddleware 長時間運用 | 🔒 | |
+| [FT28](2026-05-field-trial-28.md) | ThrottleMiddleware パスごとレート制限 | | |
+| [FT29](2026-05-field-trial-29.md) | AsyncUseCaseProtocol 実運用 | | |
+| [FT30](2026-05-field-trial-30.md) | RequestLoggingMiddleware + structlog バインディング | 🔒 | |
+| [FT31](2026-05-field-trial-31.md) | DatabaseHealthCheck + ヘルスエンドポイント | | |
+| [FT32](2026-05-field-trial-32.md) | SecurityHeadersMiddleware CSP カスタマイズ | | |
+| [FT33](2026-05-field-trial-33.md) | ValidationException カスタムエラーコード | 🔒 | |
+| [FT34](2026-05-field-trial-34.md) | DatabaseIntegrityException + SimpleDomainHandler | | |
+| [FT35](2026-05-field-trial-35.md) | 混合認証（Bearer Token OR API Key） | | |
+| [FT36](2026-05-field-trial-36.md) | CompositeHealthCheck | 🔒 | |
+| [FT37](2026-05-field-trial-37.md) | PaginationResponse + PaginationQueryParser | | |
+| [FT38](2026-05-field-trial-38.md) | SqlAlchemyTransactionManager.transactional() | | |
+| [FT39](2026-05-field-trial-39.md) | RequestSizeLimitMiddleware | 🔒 | |
+| [FT40](2026-05-field-trial-40.md) | 多ドメイン連携（Article + Tag） | | |
+| [FT41](2026-05-field-trial-41.md) | structlog テスト統合 — configure_for_testing() + caplog | | |
+| [FT42](2026-05-field-trial-42.md) | get_request_id() Depends + configure_problem_details() | 🔒 | |
+| [FT43](2026-05-field-trial-43.md) | ThrottleMiddleware path_limits | | |
+| [FT44](2026-05-field-trial-44.md) | PaginationQueryParser + PaginationResponse | | |
+| [FT45](2026-05-field-trial-45.md) | SecurityHeadersMiddleware 詳細カスタマイズ | 🔒 | |
+| [FT46](2026-05-field-trial-46.md) | DatabaseIntegrityException | | |
+| [FT47](2026-05-field-trial-47.md) | SqlAlchemyTransactionManager.transactional() | | |
+| [FT48](2026-05-field-trial-48.md) | CompositeHealthCheck + AsyncCompositeHealthCheck | 🔒 | |
+| [FT49](2026-05-field-trial-49.md) | AppSettings | | |
+| [FT50](2026-05-field-trial-50.md) | ValidationException + ValidationCode(StrEnum) | | |
+| [FT51](2026-05-field-trial-51.md) | SimpleDomainHandler | 🔒 | |
+| [FT52](2026-05-field-trial-52.md) | ミドルウェアスタック組み合わせ | | |
+| [FT53](2026-05-field-trial-53.md) | ApiKeyAuthMiddleware | | |
+| [FT54](2026-05-field-trial-54.md) | RequestSizeLimitMiddleware + path_limits | 🔒 | |
+| [FT55](2026-05-field-trial-55.md) | parse_db_datetime | | |
+| [FT56](2026-05-field-trial-56.md) | CompositeHealthCheck + http_status_code | | |
+| [FT57](2026-05-field-trial-57.md) | AsyncCompositeHealthCheck | 🔒 | |
+| [FT58](2026-05-field-trial-58.md) | ThrottleMiddleware | | |
+| [FT59](2026-05-field-trial-59.md) | SecurityHeadersMiddleware | | |
+| [FT60](2026-05-field-trial-60.md) | RequestIdMiddleware | 🔒 | |
+| [FT61](2026-05-field-trial-61.md) | AsyncUseCaseProtocol | | |
+| [FT62](2026-05-field-trial-62.md) | RequestLoggingMiddleware | | |
+| [FT63](2026-05-field-trial-63.md) | configure_problem_details / PROBLEM_DETAILS_BASE_URL | 🔒 | |
+| [FT64](2026-05-field-trial-64.md) | ValidationException 複数エラー | | |
+| [FT65](2026-05-field-trial-65.md) | DatabaseHealthCheck | | |
+| [FT66](2026-05-field-trial-66.md) | AppSettings | 🔒 | |
+| [FT67](2026-05-field-trial-67.md) | SqlAlchemyTransactionManager | | |
+| [FT68](2026-05-field-trial-68.md) | SimpleDomainHandler + extra_factory | | |
+| [FT69](2026-05-field-trial-69.md) | PaginationQueryParser + PaginationResponse | 🔒 | |
+| [FT70](2026-05-field-trial-70.md) | 複数ドメイン連携 | | |
+| [FT71](2026-05-field-trial-71.md) | 完全レイヤードアーキテクチャ | | |
+| [FT72](2026-05-field-trial-72.md) | DatabaseIntegrityException + write() 戻り値パターン | 🔒 | |
+| [FT73](2026-05-field-trial-73.md) | PaginationQueryParser.parse() 静的メソッド | | |
+| [FT74](2026-05-field-trial-74.md) | カスタム HealthCheckProtocol 実装 | | |
+| [FT75](2026-05-field-trial-75.md) | ミドルウェアスタック順序依存性 | 🔒 | |
+| [FT76](2026-05-field-trial-76.md) | async ハンドラー + sync SQLAlchemy イベントループブロッキング | | |
+| [FT77](2026-05-field-trial-77.md) | BearerToken + ApiKey 混在認証 | | |
+| [FT78](2026-05-field-trial-78.md) | ThrottleMiddleware 境界動作 | 🔒 | |
+| [FT79](2026-05-field-trial-79.md) | RequestLoggingMiddleware と構造化ログ | | |
+| [FT80](2026-05-field-trial-80.md) | MCP E2E — LocalMcpServer + HttpxMcpClient | | |
+
+---
+
+## カテゴリ3: 応用パターン検証 (FT81〜FT120)
+
+| FT# | テーマ | 診断 | Follow-up |
+|-----|--------|------|-----------|
+| [FT81](2026-05-field-trial-81.md) | CORS — setup_middlewares() + CORSMiddleware | 🔒 | |
+| [FT82](2026-05-field-trial-82.md) | Background Tasks — FastAPI BackgroundTasks | | |
+| [FT83](2026-05-field-trial-83.md) | Depends() DI — nene2 アーキテクチャ統合 | | |
+| [FT84](2026-05-field-trial-84.md) | 認証 Depends ユーティリティ — CurrentUser / require_auth | 🔒 | |
+| [FT85](2026-05-field-trial-85.md) | OpenAPI スキーマ品質 — JSONResponse と response_model | | |
+| [FT86](2026-05-field-trial-86.md) | Lifespan イベント — startup/shutdown | | |
+| [FT87](2026-05-field-trial-87.md) | カスタムレスポンスヘッダー — X-Total-Count / X-RateLimit | 🔒 | |
+| [FT88](2026-05-field-trial-88.md) | ドメインイベント — 同期イベントバスパターン | | |
+| [FT89](2026-05-field-trial-89.md) | カスタムバリデーション — Pydantic + ValidationException 統合 | | |
+| [FT90](2026-05-field-trial-90.md) | ファイルアップロード — multipart/form-data | 🔒 | |
+| [FT91](2026-05-field-trial-91.md) | ストリーミングレスポンス — StreamingResponse + SSE | | |
+| [FT92](2026-05-field-trial-92.md) | APIRouter パターン | | |
+| [FT93](2026-05-field-trial-93.md) | Dependency Override パターン | 🔒 | |
+| [FT94](2026-05-field-trial-94.md) | ミドルウェア順序とエラーレスポンスのヘッダー | | |
+| [FT95](2026-05-field-trial-95.md) | Pydantic model_validator / field_validator + nene2 統合 | | |
+| [FT96](2026-05-field-trial-96.md) | カスタム例外ハンドラーと ErrorHandlerMiddleware 共存 | 🔒 | |
+| [FT97](2026-05-field-trial-97.md) | HTTP キャッシュヘッダー (ETag / Cache-Control) | | |
+| [FT98](2026-05-field-trial-98.md) | PATCH / Partial Update パターン | | |
+| [FT99](2026-05-field-trial-99.md) | Webhook HMAC-SHA256 署名検証 | 🔒 | |
+| [FT100](2026-05-field-trial-100.md) | In-memory TTL レスポンスキャッシュ | | |
+| [FT101](2026-05-field-trial-101.md) | Query Parameter Filter/Sort パターン | | |
+| [FT102](2026-05-field-trial-102.md) | response_model と PaginationResponse の型整合性 | 🔒 | |
+| [FT103](2026-05-field-trial-103.md) | カスタムミドルウェアで認証情報をリクエストスコープに格納 | | |
+| [FT104](2026-05-field-trial-104.md) | AsyncIterator を返す UseCase + StreamingResponse | | |
+| [FT105](2026-05-field-trial-105.md) | マルチテナント DB 接続 | 🔒 | |
+| [FT106](2026-05-field-trial-106.md) | Idempotency Key パターン | | |
+| [FT107](2026-05-field-trial-107.md) | Bulk Operations（一括作成・削除） | | |
+| [FT108](2026-05-field-trial-108.md) | Pydantic computed_field と property パターン | 🔒 | |
+| [FT109](2026-05-field-trial-109.md) | API バージョニング（v1/v2 ルーティング） | | |
+| [FT110](2026-05-field-trial-110.md) | ソフトデリート（論理削除）パターン | | |
+| [FT111](2026-05-field-trial-111.md) | カーソルベースページネーション | 🔒 | |
+| [FT112](2026-05-field-trial-112.md) | バルクアップデート（PATCH /items/bulk） | | |
+| [FT113](2026-05-field-trial-113.md) | Pydantic 識別共用体（Discriminated Union） | | |
+| [FT114](2026-05-field-trial-114.md) | プラグインレジストリパターン | 🔒 | |
+| [FT115](2026-05-field-trial-115.md) | structlog 構造化ログ + リクエストコンテキスト伝播 | | |
+| [FT116](2026-05-field-trial-116.md) | @contextmanager リソース管理 + FastAPI lifespan | | |
+| [FT117](2026-05-field-trial-117.md) | TypedDict + @overload による型安全な辞書操作 | 🔒 | |
+| [FT118](2026-05-field-trial-118.md) | Python match 文パターンマッチング | | |
+| [FT119](2026-05-field-trial-119.md) | functools.lru_cache / cache による関数レベルキャッシュ | | |
+| [FT120](2026-05-field-trial-120.md) | dataclasses.field 高度な使い方 | 🔒 | |
+
+---
+
+## カテゴリ4: Python 標準ライブラリ検証 (FT121〜FT177)
+
+| FT# | テーマ | 診断 | Follow-up |
+|-----|--------|------|-----------|
+| [FT121](2026-05-field-trial-121.md) | asyncio.gather + asyncio.TaskGroup 並列処理 | 🔒 | |
+| [FT122](2026-05-field-trial-122.md) | 型安全なインプロセス イベントバス | | |
+| [FT123](2026-05-field-trial-123.md) | pydantic.SecretStr + 環境変数セキュアな設定管理 | | |
+| [FT124](2026-05-field-trial-124.md) | pathlib.Path + セキュアなファイル操作 | 🔒 | |
+| [FT125](2026-05-field-trial-125.md) | Python 3.12 ジェネリッククラス + Pydantic Generic | | |
+| [FT126](2026-05-field-trial-126.md) | StrEnum / IntEnum の高度な活用 | | |
+| [FT127](2026-05-field-trial-127.md) | collections モジュールの高度な活用 | 🔒 | |
+| [FT128](2026-05-field-trial-128.md) | itertools モジュール | | |
+| [FT129](2026-05-field-trial-129.md) | functools モジュール | | |
+| [FT130](2026-05-field-trial-130.md) | operator + heapq + bisect | 🔒 | |
+| [FT131](2026-05-field-trial-131.md) | デスクリプタープロトコル | | |
+| [FT132](2026-05-field-trial-132.md) | __init_subclass__ + クラスデコレーター | | |
+| [FT133](2026-05-field-trial-133.md) | contextlib の高度な活用 | 🔒 | |
+| [FT134](2026-05-field-trial-134.md) | typing モジュール | | |
+| [FT135](2026-05-field-trial-135.md) | abc モジュール + 抽象基底クラス | | |
+| [FT136](2026-05-field-trial-136.md) | re モジュール | 🔒 | |
+| [FT137](2026-05-field-trial-137.md) | datetime + zoneinfo | | |
+| [FT138](2026-05-field-trial-138.md) | decimal + fractions + statistics | | |
+| [FT139](2026-05-field-trial-139.md) | concurrent.futures + threading | 🔒 | |
+| [FT140](2026-05-field-trial-140.md) | io モジュール + バイナリ処理 | | |
+| [FT141](2026-05-field-trial-141.md) | asyncio 高度機能 | | |
+| [FT142](2026-05-field-trial-142.md) | uuid モジュール | 🔒 | |
+| [FT143](2026-05-field-trial-143.md) | inspect モジュール | | |
+| [FT144](2026-05-field-trial-144.md) | logging 高度機能 | | |
+| [FT145](2026-05-field-trial-145.md) | weakref モジュール | 🔒 | |
+| [FT146](2026-05-field-trial-146.md) | copy モジュール | | |
+| [FT147](2026-05-field-trial-147.md) | urllib.parse モジュール | | |
+| [FT148](2026-05-field-trial-148.md) | json 高度機能 | 🔒 | |
+| [FT149](2026-05-field-trial-149.md) | csv モジュール | | |
+| [FT150](2026-05-field-trial-150.md) | configparser モジュール | | |
+| [FT151](2026-05-field-trial-151.md) | argparse モジュール | 🔒 | |
+| [FT152](2026-05-field-trial-152.md) | hashlib モジュール（初回） | | |
+| [FT153](2026-05-field-trial-153.md) | struct モジュール | | |
+| [FT154](2026-05-field-trial-154.md) | array モジュールと memoryview | 🔒 | |
+| [FT155](2026-05-field-trial-155.md) | queue モジュール | | |
+| [FT156](2026-05-field-trial-156.md) | threading モジュール | | |
+| [FT157](2026-05-field-trial-157.md) | multiprocessing モジュール | 🔒 | |
+| [FT158](2026-05-field-trial-158.md) | tempfile モジュール | | |
+| [FT159](2026-05-field-trial-159.md) | fnmatch と glob モジュール | | |
+| [FT160](2026-05-field-trial-160.md) | difflib モジュール | 🔒 | |
+| [FT161](2026-05-field-trial-161.md) | shutil モジュール | | |
+| [FT162](2026-05-field-trial-162.md) | zipfile モジュール | | |
+| [FT163](2026-05-field-trial-163.md) | sqlite3 モジュール | 🔒 | |
+| [FT164](2026-05-field-trial-164.md) | contextlib モジュール（再検証） | | |
+| [FT165](2026-05-field-trial-165.md) | secrets モジュール | | |
+| [FT166](2026-05-field-trial-166.md) | functools モジュール（再検証） | 🔒 | |
+| [FT167](2026-05-field-trial-167.md) | enum モジュール | | |
+| [FT168](2026-05-field-trial-168.md) | re モジュール（再検証） | | |
+| [FT169](2026-05-field-trial-169.md) | typing モジュール（再検証） | 🔒 | |
+| [FT170](2026-05-field-trial-170.md) | collections モジュール（再検証） | | |
+| [FT171](2026-05-field-trial-171.md) | asyncio モジュール（再検証） | | |
+| [FT172](2026-05-field-trial-172.md) | dataclasses モジュール | 🔒🔍 | |
+| [FT173](2026-05-field-trial-173.md) | pathlib モジュール（再検証） | | |
+| [FT174](2026-05-field-trial-174.md) | itertools モジュール（再検証） | 🔒 | |
+| [FT175](2026-05-field-trial-175.md) | logging モジュール — SensitiveFilter / RequestIdAdapter | | |
+| [FT176](2026-05-field-trial-176.md) | decimal モジュール — 金融計算・精度制御 | 🔍 | [#499](https://github.com/hideyukiMORI/nene2-python/issues/499) [#500](https://github.com/hideyukiMORI/nene2-python/issues/500) |
+| [FT177](2026-05-field-trial-177.md) | hashlib モジュール — PBKDF2 / scrypt / Blake2 | 🔒 | [#501](https://github.com/hideyukiMORI/nene2-python/issues/501) |
+
+---
+
+## セキュリティ診断実施済み一覧（🔒）
+
+FT3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48, 51, 54, 57, 60, 63, 66, 69, 72, 75, 78, 81, 84, 87, 90, 93, 96, 99, 102, 105, 108, 111, 114, 117, 120, 121, 124, 127, 130, 133, 136, 139, 142, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172, 174, 177
+
+合計: **60件**（177 FT 中 約 34%）
+
+## クラッカーペンテスト実施済み一覧（🔍）
+
+FT172, FT176
+
+---
+
+*最終更新: 2026-05-21 (FT177 / v1.8.48)*

nene2_python-1.8.49/docs/todo/current.md

@@ -0,0 +1,63 @@
+# TODO — current
+
+最終更新: 2026-05-21
+現状: **v1.8.48 安定版 / フィールドトライアルループ継続中（FT177 完了）**
+
+---
+
+## 状態サマリー
+
+v1.8.48 完了済み。FT177（hashlib / PBKDF2・scrypt・Blake2）を含む FT177 件を実施済み。
+フィールドトライアルループは FT178 以降も継続中。
+
+---
+
+## オープン PR
+
+なし（現在 main ブランチはクリーン）
+
+---
+
+## オープン Issue（優先度順）
+
+| Issue | 内容 | 優先度 |
+|---|---|---|
+| [#501](https://github.com/hideyukiMORI/nene2-python/issues/501) | [FT177] FastAPI アプリファクトリで APIRouter パターンを標準化 | 中 |
+| [#500](https://github.com/hideyukiMORI/nene2-python/issues/500) | [FT176] parse_decimal_safe() の Unicode 全角数字受け入れ挙動を文書化 | 低 |
+| [#499](https://github.com/hideyukiMORI/nene2-python/issues/499) | [FT176] calculate_tax/discount にビジネスロジックバリデーション追加 | 中 |
+
+---
+
+## 直近の完了マイルストーン
+
+| バージョン | 主な内容 |
+|---|---|
+| v1.8.48 | FT177: hashlib — PBKDF2 / scrypt / Blake2 キー付きハッシュ |
+| v1.8.47 | FT176: decimal — 金融計算・精度制御（クラッカーペンテスト実施） |
+| v1.8.46 | FT175: logging — SensitiveFilter / RequestIdAdapter |
+| v1.8.45 | FT174: itertools — 安全な組み合わせ計算（セキュリティ診断実施） |
+| v1.8.44 | FT173: pathlib — セキュアなファイル操作 |
+| v1.8.43 | FT172: dataclasses — フリーズ・スロット・バリデーション（診断＋ペンテスト） |
+
+---
+
+## フィールドトライアル進捗
+
+**実施済み**: FT1〜FT177（全 177 件）
+
+索引: [`docs/field-trials/INDEX.md`](../field-trials/INDEX.md)
+
+**次のアクション**:
+- FT178 以降を継続（FT180 は 180 % 4 = 0 → クラッカーペンテスト対象）
+- FT180 は 180 % 3 = 0 → セキュリティ診断も実施
+
+---
+
+## 改善検討事項
+
+| 課題 | 優先度 | 備考 |
+|---|---|---|
+| PostgreSQL / MySQL 実 DB 統合テスト | 中〜高 | CI に Docker service ジョブを追加検討 |
+| PyJWT 推移的 CVE（PYSEC-2025-183） | 低 | mcp 側の修正を待ち。文書化済み |
+| APIRouter パターンを FT テンプレートに反映 | 中 | Issue #501 |
+| FT サマリ索引 | 完了 | `docs/field-trials/INDEX.md` 作成済み |

{nene2_python-1.8.48 → nene2_python-1.8.49}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.48"
+version = "1.8.49"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}
@@ -60,6 +60,7 @@ dev = [
     "mypy>=1.13",
     "ruff>=0.9",
     "pip-audit>=2.7",
+    "psycopg2-binary>=2.9.12",
 ]
 
 # ---------------------------------------------------------------------------

nene2_python-1.8.48/docs/todo/current.md

@@ -1,52 +0,0 @@
-# TODO — current
-
-最終更新: 2026-05-20
-現状: **v1.8.33 安定版 / フィールドトライアルループ継続中**
-
----
-
-## 状態サマリー
-
-v1.8.33 完了済み。フィールドトライアル FT108/FT109 を含む docs 改善マージ済み。
-2026-05-20 時点でオープン PR は PR #428（ResourceWarning 修正）のみ。
-
----
-
-## オープン PR
-
-| PR | Issue | 内容 |
-|---|---|---|
-| [#428](https://github.com/hideyukiMORI/nene2-python/pull/428) | #427 | テストの ResourceWarning: unclosed database を解消する |
-
----
-
-## 直近の完了マイルストーン
-
-| バージョン | 主な追加機能 |
-|---|---|
-| v1.8.33 | `nene2.cache.TtlCache[V]` |
-| v1.8.32 | `nene2.security.verify_hmac_signature()` |
-| v1.8.31 | `nene2.http.generate_etag()` |
-| v1.8.30 | `problem_details_response()` headers パラメーター |
-| v1.8.29 | `make_require_auth()` |
-| v1.8.28 | `PaginationDep`, `PaginationResponse.model_dump()` |
-
----
-
-## フィールドトライアル進捗
-
-**実施済み**: FT1〜FT109（FT108, FT109 含む docs-only）
-
-**次のアクション候補**（優先度順）:
-1. ResourceWarning 修正 PR #428 マージ後、バグ修正リリース（v1.8.34）
-2. FT110+ — 未検証パターンの探索継続
-3. DB 実統合テスト（PostgreSQL/MySQL 実環境）の追加検討
-4. PyPI 公開体験の最終確認
-
----
-
-## 改善検討事項
-
-- 警告ゼロ化: PR #428 でほぼ解消（StaticPool の 1 件は filterwarnings で抑制）
-- DB 実統合テスト: SQLite インメモリテストはあるが PostgreSQL/MySQL 実環境テストは未
-- PyPI 公開体験の仕上げ: パッケージメタデータ整備済み、公開フロー最終確認が残