nene2-python 1.8.45__tar.gz → 1.8.47__tar.gz

{nene2_python-1.8.45 → nene2_python-1.8.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.45
+Version: 1.8.47
 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.47/docs/field-trials/2026-05-field-trial-175.md

@@ -0,0 +1,271 @@
+# FT175: logging モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `logging` モジュール — センシティブデータマスキング・LoggerAdapter・dictConfig
+**セキュリティ診断**: なし（FT176 で実施）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `logging` モジュールを検証する。
+CLAUDE.md で「`print()` 禁止・`logging` モジュールのみ使用」と明示されており、
+nene2-python の根幹ポリシーに直結するモジュールである。
+
+このFTで確認する点:
+- `logging.Filter` によるセンシティブデータのマスキング（パスワード・トークン・カード番号）
+- `logging.LoggerAdapter` によるリクエストIDの全ログへの付与
+- `setup_logger()` パターン（テスト用 StringIO へのキャプチャ）
+- `parse_log_level()` によるログレベルの安全な変換
+- `logging.config.dictConfig` による宣言的ログ設定
+- `capture_logs()` / `release_capture()` テストユーティリティ
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft175-logging/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `mask_sensitive(message)` | パスワード・トークン・API鍵・カード番号をマスク |
+| `SensitiveFilter` | `logging.Filter` サブクラス — LogRecord のメッセージを自動マスク |
+| `RequestIdAdapter` | `LoggerAdapter[Logger]` — 全ログに `[request_id]` を付与 |
+| `setup_logger(name, level, stream)` | テスト用 StringIO 出力ロガーを作成 |
+| `parse_log_level(level_str)` | 文字列 → `logging.DEBUG` 等の定数、不明は `INFO` |
+| `log_event(logger, level, message, extra)` | 構造化ログエントリ（辞書）を記録して返す |
+| `is_level_enabled(logger, level)` | ログレベルが有効かを `bool` で返す |
+| `effective_level_name(logger)` | 有効ログレベル名を文字列で返す |
+| `LOGGING_CONFIG` | `dictConfig` 用設定辞書（SensitiveFilter 組み込み） |
+| `apply_logging_config()` | dictConfig を適用する |
+| `capture_logs(logger)` | テスト用キャプチャハンドラーを追加して `(StringIO, handler)` を返す |
+| `release_capture(logger, handler)` | キャプチャハンドラーを解放する |
+
+マスキングパターン:
+
+| パターン | 置換後 |
+|---|---|
+| `password=<4文字以上>` | `password=***` |
+| `token: <4文字以上>` | `token: ***` |
+| `api_key=<4文字以上>` | `api_key=***` |
+| `\b\d{13,19}\b`（カード番号） | `****-****-****-****` |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/logging/mask` | センシティブデータをマスクした文字列を返す |
+| GET | `/logging/level` | ロガーのレベル有効判定 |
+| POST | `/logging/event` | イベントを記録（センシティブマスク付き） |
+| GET | `/logging/events` | 記録済みイベント一覧 |
+| DELETE | `/logging/events` | イベント一覧をクリア |
+| GET | `/logging/parse-level` | 文字列をログレベル数値に変換 |
+| GET | `/logging/buffer` | インメモリバッファのログ行一覧 |
+
+---
+
+## テスト結果
+
+**32 passed**
+
+```
+32 passed in 0.34s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `logging.StreamHandler` のジェネリック型注釈（深刻度: 低）
+
+**事象**: `logging.StreamHandler` は `StreamHandler[StringIO]` とジェネリック型注釈できるが、
+mypy が `# type: ignore[type-arg]` なしでは警告を出すケースがある。
+
+**原因**: `StreamHandler` は Python 3.12 でジェネリック対応済みだが、
+`StreamHandler` の型スタブが `Generic[TextIO]` として定義されているため
+`StreamHandler` 単独だと型引数省略警告が出ることがある。
+
+**対応**: 関数シグネチャに `# type: ignore[type-arg]` を追記。
+これは mypy の型スタブ側の制約であり実装ミスではないため、CLAUDE.md 規約に従いコード添付コメントで理由を明記した。
+
+### F-2: `LoggerAdapter.extra` の型（深刻度: 低）
+
+**事象**: `LoggerAdapter[Logger]` の `self.extra` の型が `Mapping[str, Any] | None` なので
+`self.extra.get("request_id")` の前に `if self.extra` のガードが必要。
+
+**原因**: `LoggerAdapter.__init__` の `extra` パラメーターが `Mapping[str, Any] | None` で
+初期化できるため、mypy がnullチェックを要求する。
+
+**対応**: `request_id = self.extra.get("request_id", "-") if self.extra else "-"` で対応。
+
+---
+
+## 観察点
+
+### 観察1: `SensitiveFilter` によるパイプライン的マスキング
+
+```python
+class SensitiveFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = mask_sensitive(str(record.msg))
+        if record.args:
+            if isinstance(record.args, dict):
+                record.args = {k: mask_sensitive(str(v)) for k, v in record.args.items()}
+            elif isinstance(record.args, tuple):
+                record.args = tuple(mask_sensitive(str(a)) for a in record.args)
+        return True
+```
+
+`logging.Logger.info("user %s password=%s", username, password)` のように
+フォーマット引数を分離して渡すケースでは `record.args` をマスクする必要がある。
+`record.msg` だけマスクしても `%s` 置換後の最終文字列に平文が現れるためである。
+
+### 観察2: `RequestIdAdapter` でコンテキストを注入する
+
+```python
+class RequestIdAdapter(logging.LoggerAdapter[logging.Logger]):
+    def process(self, msg: str, kwargs: Any) -> tuple[str, Any]:
+        request_id = self.extra.get("request_id", "-") if self.extra else "-"
+        return f"[{request_id}] {msg}", kwargs
+```
+
+FastAPI のリクエストスコープで `RequestIdAdapter` インスタンスを生成し、
+同一リクエスト内の全ログに `[req-xxxxxxxx]` プレフィックスを付与できる。
+`logging.getLogger()` グローバルシングルトンと異なり、スコープごとに別インスタンスを作れる。
+
+### 観察3: `parse_log_level` の安全な変換
+
+```python
+def parse_log_level(level_str: str) -> int:
+    level = logging.getLevelName(level_str.upper())
+    if not isinstance(level, int):  # 不明な文字列は int ではなく文字列を返す
+        return logging.INFO
+    return level
+```
+
+`logging.getLevelName("UNKNOWN")` は `"Level UNKNOWN"` という文字列を返す（None ではない）。
+`isinstance(level, int)` チェックでフォールバックを実装する必要がある。
+
+### 観察4: `dictConfig` で `SensitiveFilter` を `()` 形式でインスタンス化
+
+```python
+"filters": {
+    "sensitive": {
+        "()": SensitiveFilter,  # クラスを直接参照してインスタンス化
+    },
+},
+```
+
+`logging.config.dictConfig` では `"()"` キーを使ってカスタムクラスのコンストラクターを呼べる。
+`class` キーは `logging` 組み込みクラスのみに使われ、カスタムクラスには `()` を使う。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- nene2-python の `nene2.log` には `structlog` ベースの設定が既に存在する。
+  `logging` モジュールの `SensitiveFilter` パターンは `structlog` の `processor` と
+  役割が対応する（`structlog` では `ProcessorFormatter` で同様のマスキングが可能）
+- CLAUDE.md の「`logging` モジュールのみ使用（`print()` 禁止）」を実証する FT となった
+- `RequestIdAdapter` と nene2 の `RequestIdMiddleware` が生成する `x-request-id` を
+  連動させることで、ログとHTTPレスポンスの追跡IDを統一できる
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`logging.basicConfig(level=logging.DEBUG)` から入る人には、
+`logging.Filter` のサブクラス化は最初のハードルになる。
+
+**ドキュメント理解**: `filter()` が `True` を返すとログ通過、`False` で破棄という
+Python の慣習は直感と逆に感じる場合がある（True = 「フィルターを通す」という意味）。  
+**事故リスク**: 高。`record.args` のマスクを忘れてフォーマット引数に平文パスワードが
+残るパターンは気づきにくい。`SensitiveFilter` のような共通フィルターを強制するのが安全。  
+**規約の使いやすさ**: `setup_logger()` ファクトリ関数でテスト・本番の切り替えができる。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`print()` から `logging` への移行は「なぜ面倒なことをするのか」と感じやすい層。
+センシティブデータの事故事例を見せることが動機付けに有効。
+
+**コピペ可能性**: `setup_logger()` はそのままコピーして使える。  
+**拡張時の罠**: `logger.propagate = False` を忘れると親ロガーにも出力され、
+二重ログ・センシティブデータ漏洩につながる。  
+**セキュリティ的な事故リスク**: 高。パスワードをログに書いて CloudWatch / Datadog に流れた
+インシデントは実際に多数報告されている。`SensitiveFilter` は必須。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+Node.js の `winston` / `pino` と比較すると Python の `logging` は低レベル API に感じるが、
+`dictConfig` による宣言的設定で同様の構成が可能。
+
+**エラーレスポンスの質**: `/logging/mask` エンドポイントで
+「original_length（入力長）+ masked（マスク後）」を返す設計でクライアント側が動作確認しやすい。  
+**Python 固有概念の学習コスト**: `LogRecord` の `msg` と `args` の分離は
+Python %-style フォーマットの知識が必要で、JS 開発者には説明が必要。  
+**事故リスク**: 中。HTTP API として使う分には Pydantic が入力を保護している。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `LOGGING` 設定辞書と `dictConfig` はほぼ同じ形式なので即理解できる。
+`SensitiveFilter` の `record.args` マスクは見落としがちなポイントで評価が高い。
+
+**他フレームワークとの差異**: Django の `LOGGING` は `dictConfig` のラッパー。
+FastAPI では自前で `logging.config.dictConfig()` を `lifespan` で呼ぶ必要がある。  
+**nene2-python の薄さへの評価**: `structlog` との共存方法を明確にするドキュメントがほしい。  
+**本番投入可能性**: `SensitiveFilter` + `RequestIdAdapter` のペアは本番環境でそのまま使える品質。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+`record.args` のマスク実装が適切。ただし `%` フォーマット以外（`{}`形式）への対応が未検討。
+
+**コードレビューチェックポイント**:
+- [x] `SensitiveFilter.filter()` が `record.args` も処理しているか — OK
+- [x] `mask_sensitive()` の正規表現が ReDoS リスクを持っていないか — `[^\s,\"'&;]{4,}` は量指定子が単純で爆発しない ✅
+- [ ] `logging.LogRecord.args` が `dict` / `tuple` 以外の型（例: `int`）のとき `isinstance` チェックが抜ける — `else` ブロックなし（稀なケースで問題発生する可能性）
+- [ ] `_LOGGED_EVENTS: list[dict]` がモジュールレベルのグローバル変数 — 複数 `create_app()` 呼び出し時に状態が混在する
+
+**チームでの安全な共有パターン**: `SensitiveFilter` を `nene2.log` に組み込み、
+デフォルトで全ロガーに適用される設計が理想。  
+**ツール追加の必要性**: `ruff S314` (print statement) は `print()` を禁止するが、
+Python 3 では `print` は関数なので別アプローチ（プリコミットフック等）が必要。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md の「`logging` モジュールのみ使用」ポリシーを、実際の使用パターンとして実証した。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 中（`record.args` マスク忘れのリスクがある）  
+**設計上の負債・ドキュメント不足**:
+- `nene2.log` の `structlog` 設定と標準 `logging` の共存について ADR が必要
+- `SensitiveFilter` を `nene2-python` フレームワーク本体に組み込む価値がある
+- `LOGGING_CONFIG` 辞書は `nene2.log` の設定と統一すべき
+
+**Follow-up Issue 候補**: `SensitiveFilter` を `nene2.middleware` または `nene2.log` に追加
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `SensitiveFilter` を `nene2.log` または `nene2.middleware` に追加 | feat |
+| 中 | `structlog` と標準 `logging` の共存 ADR を作成 | docs |
+| 低 | `SensitiveFilter.filter()` の `record.args` が dict/tuple 以外のとき `str` として処理する | fix |
+
+---
+
+## まとめ
+
+FT175 では `logging` モジュールの実践的パターンを実証した。
+`SensitiveFilter` による `record.args` を含む完全マスキング、
+`RequestIdAdapter` によるリクエストスコープのコンテキスト注入、
+`dictConfig` による宣言的設定が核心。
+`record.args` のマスク忘れは実際の本番事故につながるため、
+`SensitiveFilter` を nene2-python フレームワーク本体に取り込むことを検討すべき。
+
+次の FT176 は 176 % 3 = 2 → セキュリティ診断なし。176 % 4 = 0 → クラッカーペンテスト実施。

nene2_python-1.8.47/docs/field-trials/2026-05-field-trial-176.md

@@ -0,0 +1,341 @@
+# FT176: decimal モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `decimal.Decimal` による精度の高い十進数演算・金融計算・丸め制御
+**セキュリティ診断**: なし（FT177 で実施）
+**クラッカーペンテスト**: **あり**（FT176: 172 + 4 = 176）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `decimal` モジュールを検証する。
+`float` の浮動小数点誤差（`0.1 + 0.2 != 0.3`）を回避し、
+金融計算で必要な「正確な十進数演算」を `Decimal` 型で実装する。
+
+このFTで確認する点:
+- `float` と `Decimal` の精度差（`0.1 + 0.2 == 0.3` の違い）
+- `quantize()` による丸めモードの制御（ROUND_HALF_UP, ROUND_HALF_EVEN 等）
+- 税計算・割引計算・割り勘といった金融計算パターン
+- `Infinity`, `NaN`, 空文字列等の不正入力への防御
+- `parse_decimal_safe()` によるバリデーション（`is_finite()` によるInf/NaN ブロック）
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft176-decimal/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `decimal_add/sub/mul/div(a, b)` | 基本四則演算（ゼロ除算は `None`） |
+| `round_decimal(value, places, mode)` | 指定モードで丸める |
+| `truncate_decimal(value, places)` | `ROUND_FLOOR` で切り捨て |
+| `ceil_decimal(value, places)` | `ROUND_CEILING` で切り上げ |
+| `ROUNDING_MODES` | 6種の丸めモード辞書 |
+| `calculate_tax(price, tax_rate)` | 税計算（ROUND_HALF_UP） |
+| `calculate_discount(price, discount_percent)` | 割引計算 |
+| `split_bill(total, num_people)` | 割り勘（ROUND_CEILING）|
+| `float_precision_demo()` | float vs Decimal 精度比較 |
+| `parse_decimal_safe(value)` | Infinity/NaN/長すぎる文字列をブロック |
+| `is_valid_decimal(value)` | バリデーション bool |
+| `compare_decimals(a, b)` | 大小比較（-1/0/1） |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/decimal/add` | 加算 |
+| POST | `/decimal/sub` | 減算 |
+| POST | `/decimal/mul` | 乗算 |
+| POST | `/decimal/div` | 除算（ゼロ除算 422） |
+| POST | `/decimal/round` | 丸め（truncated, ceiling も返す） |
+| POST | `/decimal/tax` | 税計算 |
+| POST | `/decimal/discount` | 割引計算 |
+| POST | `/decimal/split-bill` | 割り勘 |
+| GET | `/decimal/float-demo` | float 精度比較デモ |
+| GET | `/decimal/validate` | Decimal バリデーション |
+| POST | `/decimal/compare` | 大小比較 |
+| GET | `/decimal/precision` | 現在の計算精度 |
+
+---
+
+## テスト結果
+
+**42 passed**
+
+```
+42 passed in 0.37s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `ROUND_HALF_EVEN`（銀行家丸め）の挙動が直感と異なる（深刻度: 低）
+
+**事象**: `round_decimal("2.5", 0, "ROUND_HALF_EVEN")` → `"2"`（偶数方向）。
+Python の組み込み `round(2.5)` も `2` を返すが（banker's rounding）、
+多くの現場では「4捨5入」を期待して `ROUND_HALF_UP` を使う。
+
+**原因**: `ROUND_HALF_EVEN` は統計的偏りを最小化するため偶数方向に丸める。
+**対応**: ドキュメントに丸めモードの違いを表で説明し、金融計算ではデフォルトを `ROUND_HALF_UP` に設定した。
+
+---
+
+## 観察点
+
+### 観察1: `float` vs `Decimal` の精度差
+
+```python
+0.1 + 0.2          # 0.30000000000000004
+Decimal("0.1") + Decimal("0.2")  # 0.3
+
+0.1 + 0.2 == 0.3   # False
+Decimal("0.1") + Decimal("0.2") == Decimal("0.3")  # True
+```
+
+`Decimal` は文字列から初期化する必要がある。`Decimal(0.1)` は float の誤差を引き継ぐ。
+
+### 観察2: `quantize()` による金融計算の標準パターン
+
+```python
+tax = (price * rate).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+```
+
+`quantize(Decimal("0.01"))` が「小数点以下2桁」を指定する慣用表現。
+`Decimal(10) ** -2` と等価。`quantize` なしで演算すると桁数が増加する。
+
+### 観察3: `Decimal("Infinity")` と `is_finite()` の組み合わせ
+
+```python
+def parse_decimal_safe(value: str) -> Decimal | None:
+    result = Decimal(value)
+    if not result.is_finite():  # Infinity / -Infinity / NaN を拒否
+        return None
+    return result
+```
+
+`Decimal("Infinity")`, `Decimal("NaN")`, `Decimal("sNaN")` は `InvalidOperation` を
+投げずに正常に生成される。`is_finite()` チェックが必要な理由がここにある。
+
+### 観察4: `split_bill` の ROUND_CEILING で全員が必ず払える金額に
+
+```python
+# 1000 / 3 = 333.333...
+# ROUND_CEILING で 333.34 に切り上げ → 全員が333.34払うと 1000.02 になるが
+# これは「端数は最初の人が多く払う」設計ではなく「全員同額で超えたら少し多い」設計
+per_person = (total / num_people).quantize(Decimal("0.01"), rounding=ROUND_CEILING)
+```
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `BinaryOpBody`, `RoundBody`, `TaxBody` 等の Pydantic モデルで `max_length=30` を設定
+- `_validate_decimal()` ヘルパーが `parse_decimal_safe()` を呼び出し、不正入力に一貫した 422 を返す
+- セキュリティヘッダーとリクエストIDが全レスポンスに付与されている
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`Decimal` のコンストラクターに **文字列**を渡す必要がある点は最初のつまずき。
+
+**ドキュメント理解**: `Decimal("0.1")` vs `Decimal(0.1)` の違いを説明する必要がある。  
+**事故リスク**: 高。`Decimal(0.1)` で float 誤差を引き継ぐコードを書きがち。  
+**規約の使いやすさ**: `parse_decimal_safe()` のファクトリ関数パターンは使いやすい。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+既存コードの `float` を `Decimal` に置換するとき `str()` 経由が必要なことを知らない。
+
+**コピペ可能性**: `calculate_tax()` パターンはそのままコピーして使える。  
+**拡張時の罠**: `quantize()` の `places` と `Decimal("0.01")` の関係が初見でわかりにくい。  
+**セキュリティ的な事故リスク**: 中。負の価格・税率のバリデーション欠如（ペンテストで発見）。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+JS の `number` 型が浮動小数点演算なので、バックエンドが `Decimal` で正確に計算することの重要性を理解できる。
+
+**エラーレスポンスの質**: 422 に `field_name` が含まれるため、フロント側のフォームバリデーションと対応しやすい。  
+**Python 固有概念の学習コスト**: `quantize` は JS には直接対応物がないが、「N桁に揃える」と説明すればわかる。  
+**事故リスク**: 低。HTTP 境界で `max_length` と `is_finite()` が守っている。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+金融システムで `Decimal` は必須。`quantize(ROUND_HALF_UP)` パターンを見れば即理解できる。
+
+**他フレームワークとの差異**: Django の `DecimalField` はモデル側で `decimal_places` を指定するが、
+このFTでは演算ごとに `quantize()` を呼ぶ明示的スタイル。どちらも正しい。  
+**nene2-python の薄さへの評価**: ドメインロジック（金融計算）が HTTP 層から完全に独立している点が評価できる。  
+**本番投入可能性**: ビジネスロジックバリデーション（範囲チェック）を追加すれば本番品質。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+ペンテストで発見されたビジネスロジック欠如（負の価格・100%超割引）は Issue 化が必要。
+
+**コードレビューチェックポイント**:
+- [x] `Infinity`, `NaN` が `is_finite()` でブロックされているか — OK
+- [x] ゼロ除算が安全に処理されているか — `decimal_div()` で None 返却 ✅
+- [ ] `calculate_tax()` の `tax_rate` に範囲制限がない — `0 <= tax_rate <= 2` 程度のバリデーションが必要
+- [ ] `calculate_discount()` の `discount_percent` が 0〜100 のチェックがない
+- [ ] Unicode 全角数字（`'１２３'`）が通過する — Decimal コンストラクターが Unicode digit を受け入れる
+
+**チームでの安全な共有パターン**: `parse_decimal_safe()` を必ず経由するルールをチーム内で徹底することが必要。  
+**ツール追加の必要性**: ruff には `Decimal(float)` を禁止するルールがないため、コードレビューで手動確認が必要。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md の「数値フィールドに `ge` / `le` / `gt` / `lt` 範囲制限があるか」ポリシーに対して、
+`Decimal` 型は文字列で受け取るため Pydantic の数値制限が適用されない点が設計的な空白。
+
+**ポリシー達成度**: 中（Pydantic で数値範囲制限できない文字列 Decimal の扱いが未定義）  
+**「初心者でも安全な API」達成度**: 中（Infinity/NaN は守られているがビジネスルール違反は通過）  
+**設計上の負債**: 文字列 Decimal の範囲バリデーションパターンをフレームワークに追加する必要がある  
+**Follow-up Issue 候補**: `Pydantic Annotated` で `DecimalStr` 型エイリアスを定義して範囲制限を組み込む
+
+---
+
+## クラッカーペンテスト（FT176: 172 + 4 = 176）
+
+> **実施方針**: 金融計算 API は「数値の正確さ」と「ビジネスロジックの整合性」の両面から攻撃できる。
+> クラッカーは価格をマイナスにして不正な返金を引き出したり、税率を異常値にして計算を崩したりする。
+
+### フェーズ1: 構造推測（攻撃者の視点）
+
+- **OpenAPI から推測できる内部構造**:
+  - 全フィールドが `str` 型 → `Decimal(str)` を内部で使っていると推測
+  - `max_length=30` → 入力サイズ制限が文字数ベース（桁数ではない）
+  - `num_people: int` に `ge=1, le=1000` → Pydantic 数値制限あり
+  - `price`, `tax_rate` に数値範囲制限なし → バリデーション欠如の可能性
+
+- **攻撃ベクターの仮説**:
+  1. `Infinity`, `NaN` を渡してランタイムエラーを引き起こす
+  2. 負の価格・100%超の税率でビジネスロジックを崩す
+  3. Unicode 文字を数値として送り込む
+  4. 科学表記（`1e100`）で予期しない巨大数を計算させる
+  5. 精度の高い計算を大量に送ってCPUを枯渇させる
+
+### フェーズ2: 攻撃実行ログ
+
+#### A. Pydantic バイパス・型強制攻撃
+
+```
+a='Infinity': 422 Invalid decimal: a='Infinity'         ← ブロック ✅
+a='-Infinity': 422                                       ← ブロック ✅
+a='NaN': 422                                             ← ブロック ✅
+a='sNaN': 422                                            ← ブロック ✅
+a='inf': 422                                             ← ブロック ✅
+a='-inf': 422                                            ← ブロック ✅
+a='nan': 422                                             ← ブロック ✅
+
+a='1e10': 200 result=10000000000                         ← 通過（有限値として正当）
+a='1E308': 200 result=1.000...E+308                      ← 通過（有限値として正当）
+a='1e100': 200 result=1.000...E+100                      ← 通過（有限値として正当）
+
+a=123 (int type): 422 string_type error                  ← Pydantic が str を要求 ✅
+```
+
+**結果**: Infinity/NaN は全7種類ブロック。科学表記は有限値として通過（許容動作）。
+
+#### B. ビジネスロジック攻撃
+
+```
+tax_rate=2.0 (200%超): 200 tax=2000.00, total=3000.00   ← 突破 ⚠️
+price=-1000 (負の価格): 200 tax=-100.00, total=-1100.00 ← 突破 ⚠️
+discount_percent=-10 (負割引): 200 → 値上がり           ← 突破 ⚠️
+discount_percent=150 (100%超): 200 discounted=-500.00   ← 突破 ⚠️
+div by zero: 422                                         ← ブロック ✅
+```
+
+**結果**: 数値範囲バリデーションが未実装のため、負の価格・異常税率が通過。
+金融 API として使う場合はビジネスロジックレベルの制約が必要。
+
+#### C. 境界値・エッジケース攻撃
+
+```
+a="" (空文字): 422 Invalid decimal                       ← ブロック ✅
+len=30 (上限ちょうど): 200                               ← 通過（正常） ✅
+len=31 (上限超え): 422 string_too_long                   ← Pydantic ブロック ✅
+28桁 all-9s + 1: 200 result=1E+28                        ← 通過（正常） ✅
+全角数字 '１２３' + 1: 200 result='124'                  ← 通過（予期しない動作）⚠️
+```
+
+**発見**: Python の `Decimal` コンストラクターは Unicode の全角数字（`'１２３'`）を受け付け、
+`123` と同じ値として扱う。`parse_decimal_safe()` は `InvalidOperation` が発生しないため通過する。
+金融 API でユーザーが全角数字を入力した場合、期待通りに動作するが、
+入力形式の正規化なしに通過することに開発者が気づいていない可能性がある。
+
+#### D. 情報収集攻撃
+
+```
+Invalid mode 'HACKED': 422 Unknown rounding mode: 'HACKED'  ← 安全なエラーメッセージ ✅
+不正入力のエラー: 内部パス・スタックトレースなし ✅
+```
+
+**結果**: エラーメッセージは適切に制御されている。
+
+#### E. DoS 試み
+
+```
+100回 div(1/3): 0.321s (3.2ms/req)                       ← 正常速度 ✅
+50回 mul(28桁×28桁): 0.163s (3.3ms/req)                  ← 正常速度 ✅
+攻撃後の精度: 28 (不変)                                   ← グローバル状態汚染なし ✅
+```
+
+**結果**: `1e100 + 1e100` のような巨大数演算も正常速度。
+`decimal.getcontext().prec` はスレッドローカルなため、攻撃による変更は他スレッドに影響しない。
+
+### フェーズ3: 攻撃まとめ
+
+| 攻撃カテゴリ | 試みた攻撃数 | 突破 | 耐えた | 予期しない動作 |
+|---|---|---|---|---|
+| Pydantic バイパス（Inf/NaN） | 7 | 0 | 7 | 0 |
+| 型強制（int型フィールド） | 1 | 0 | 1 | 0 |
+| ビジネスロジック（範囲） | 4 | 4 | 0 | 0 |
+| 境界値（長さ・文字種） | 5 | 0 | 4 | 1 |
+| 情報収集（エラー解析） | 2 | 0 | 2 | 0 |
+| DoS（大量・高精度計算） | 3 | 0 | 3 | 0 |
+
+**攻撃耐性評価**: 軽微な問題あり（ビジネスロジックバリデーション欠如）
+
+**発見した弱点**:
+1. **MEDIUM**: `calculate_tax()`, `calculate_discount()` に価格・税率・割引率の範囲制限なし
+   - 負の価格（`-1000`）→ 負の税額
+   - 200%の税率（`2.0`）→ 元価格の3倍
+   - 150%の割引（`150`）→ マイナス価格
+
+2. **LOW**: Unicode 全角数字（`'１２３'`）が `Decimal` に通過する
+   - `parse_decimal_safe` は `is_finite()` で判定するが、Unicode digit は有限値なので通過
+   - 機能的には正しく動作するが、予期しない入力形式
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 高 | `calculate_tax()`, `calculate_discount()` に価格・税率・割引率の範囲バリデーションを追加 | fix |
+| 中 | `parse_decimal_safe()` に ASCII 数字のみ許可するオプションを追加（Unicode digit の予期しない受け入れを防ぐ） | feat |
+| 中 | 文字列 Decimal の `Annotated` 型エイリアス（`PositiveDecimalStr`, `TaxRateStr`）をフレームワークに追加 | feat |
+| 低 | `Decimal(0.1)` を禁止するカスタム ruff ルールの検討 | chore |
+
+---
+
+## まとめ
+
+FT176 では `decimal.Decimal` による精度の高い金融計算を実装した。
+`float` との精度差（`0.1 + 0.2 != 0.3` 問題）、`quantize()` による丸め制御、
+`is_finite()` による `Infinity`/`NaN` ブロックを確認した。
+
+クラッカーペンテストでは Infinity/NaN の全種類が正常にブロックされたが、
+ビジネスロジックレベルのバリデーション（負の価格・100%超の税率）が欠如していることを発見した。
+金融 API では「計算として正しい値」と「ビジネスとして許容できる値」の区別が重要で、
+`parse_decimal_safe()` の技術的バリデーションだけでは不十分であることが確認された。
+
+次の FT177 は 177 % 3 = 0 → セキュリティ診断が必要。

{nene2_python-1.8.45 → nene2_python-1.8.47}/pyproject.toml

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