nene2-python 1.8.64__tar.gz → 1.8.66__tar.gz

{nene2_python-1.8.64 → nene2_python-1.8.66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.64
+Version: 1.8.66
 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.66/docs/field-trials/2026-05-field-trial-193.md

@@ -0,0 +1,296 @@
+# FT193: socket モジュール — TCP/UDP socketpair・DNS 解決・ソケットオプション
+
+**日付**: 2026-05-21
+**テーマ**: Python `socket` モジュールの基本操作を nene2-python FastAPI アプリとして実装し、低レベルネットワーク API の DX を検証する
+**セキュリティ診断**: なし（193 % 3 = 1）
+**クラッカーペンテスト**: なし（193 % 4 = 1）
+
+---
+
+## 概要
+
+`socket` モジュールは Python の BSD ソケット低レベル API。
+TCP/UDP 通信・DNS 名前解決・ソケットオプション照会などを提供する。
+FT192（asyncio）と並ぶ並行・ネットワーク系の基盤モジュールであり、
+今回は `socketpair()` を使ったインプロセスエコーで外部ネットワーク依存なしにテストする設計をとった。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft193-socket/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `dns_lookup(host, port)` | `socket.getaddrinfo` で DNS 名前解決。`match` 文で型安全にアドレスタプルを展開 |
+| `hostname_info()` | `gethostname` / `getfqdn` / `gethostbyname` でローカルホスト情報を取得 |
+| `tcp_echo_pair(message)` | `socketpair(SOCK_STREAM)` を使ったインプロセス TCP エコー |
+| `udp_echo_pair(message)` | `socketpair(SOCK_DGRAM)` を使ったインプロセス UDP エコー |
+| `socket_options_info()` | 新規 TCP ソケットのデフォルトオプション値（`SO_REUSEADDR` / `SO_SNDBUF` 等）を返す |
+| `socket_capabilities()` | IPv6 対応・デュアルスタック対応・デフォルトタイムアウトを報告 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/socket/dns-lookup` | DNS ルックアップ（`host` / `port` を受け取る） |
+| GET | `/socket/hostname` | ローカルホスト情報 |
+| POST | `/socket/tcp-echo` | TCP エコー（socketpair） |
+| POST | `/socket/udp-echo` | UDP エコー（socketpair） |
+| GET | `/socket/options` | ソケットオプション照会 |
+| GET | `/socket/capabilities` | 実行環境のソケット機能情報 |
+
+---
+
+## テスト結果
+
+**27 passed**
+
+```
+27 passed in 0.35s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `sendall(b"")` で `recv()` がブロック（深刻度: 中）
+
+**事象**: `tcp_echo_pair("")` を呼ぶと `client.sendall(b"")` が no-op になり、
+`server.recv(256)` がデータを待ち続けてテストが永久ブロックした。
+
+**原因**: TCP ソケットは `send(b"")` を実際には送出しない。
+`recv()` はソケットが閉じられるか、データが届くまで待ち続ける。
+UDP (`SOCK_DGRAM`) は 0 バイトデータグラムを送信できるため問題にならないが、
+TCP とふるまいが異なる点が開発者の盲点になりやすい。
+
+**対応**: 空メッセージを早期リターンで処理する。
+
+```python
+def tcp_echo_pair(message: str) -> EchoResult:
+    message = message[:MAX_MESSAGE_LEN]
+    # sendall(b"") は TCP ではデータを送出しないため server.recv がブロックする
+    if not message:
+        return EchoResult(sent="", received="", matched=True, byte_count=0)
+    ...
+```
+
+CLAUDE.md への追記事項なし（一般的な Python ソケット挙動）。
+
+### F-2: `socket.getaddrinfo` 戻り値の mypy 型エラー（深刻度: 低）
+
+**事象**: `info[4][0]` を `AddressInfo.address: str` に渡すと mypy が
+`Argument has incompatible type "str | int"` と報告した。
+
+**原因**: `socket.getaddrinfo` の戻り値アドレスタプルは
+`tuple[str, int] | tuple[str, int, int, int]` より広い union として typeshed が定義しており、
+`[0]` インデックスアクセスで `str | int` になる。
+
+**対応**: `match` 文の型パターンで絞り込む。
+
+```python
+match info[4]:
+    case (str() as address, int() as addr_port, *_):
+        addresses.append(AddressInfo(
+            family=info[0].name,
+            type=info[1].name,
+            address=address,
+            port=addr_port,
+        ))
+    case _:
+        pass
+```
+
+`str() as address` / `int() as addr_port` のパターンが mypy の型絞り込みを働かせ、
+`cast()` や `# type: ignore` なしで型安全に書けた。Python 3.10+ `match` の典型的な有効活用。
+
+---
+
+## 観察点
+
+### 観察1: `socketpair` でネットワーク依存なしにソケット動作を検証できる
+
+```python
+client, server = socket.socketpair(socket.AF_UNIX, socket.SOCK_STREAM)
+try:
+    client.sendall(message.encode())
+    data = server.recv(MAX_MESSAGE_LEN)
+    server.sendall(data)
+    received_bytes = client.recv(MAX_MESSAGE_LEN)
+finally:
+    client.close()
+    server.close()
+```
+
+`socketpair()` はカーネル内のパイプに近く、ネットワークスタックを経由しない。
+FT 環境でポートを bind/listen せずにソケット通信をテストするのに最適。
+`AF_UNIX + SOCK_STREAM` (TCP 相当) と `AF_UNIX + SOCK_DGRAM` (UDP 相当) の両方が使える。
+
+### 観察2: `socket.getaddrinfo` 戻り値を `match` で分岐するパターン
+
+```python
+match info[4]:
+    case (str() as address, int() as addr_port, *_):
+        # AF_INET: (host, port)
+        # AF_INET6: (host, port, flowinfo, scopeid)
+        # どちらも先頭2要素が (str, int) なのでこのパターンで捕捉できる
+        ...
+    case _:
+        pass  # 想定外のアドレス族（AF_ALG 等）はスキップ
+```
+
+`*_` で残余要素を無視しているため AF_INET4/INET6 の両方を1パターンで処理できる。
+これは Python 3.10 以降の `match` がある場合の慣用的な書き方。
+
+### 観察3: `socket.AddressFamily.name` / `socket.SocketKind.name` で読みやすい文字列を取得
+
+```python
+# info[0] は AddressFamily IntEnum なので .name でシンボル名を取得
+family=info[0].name   # "AF_INET" / "AF_INET6"
+type=info[1].name     # "SOCK_STREAM"
+```
+
+`IntEnum` の `.name` プロパティはシリアライズ時に読みやすく、
+直接 `int` を返すより API レスポンスとして価値が高い。
+
+### 観察4: `socket_capabilities()` で環境差異を明示的に記録
+
+```python
+def socket_capabilities() -> SocketCapabilities:
+    has_ipv6 = socket.has_ipv6
+    try:
+        has_dual = socket.has_dualstack_ipv6()
+    except OSError:
+        has_dual = False
+    return SocketCapabilities(
+        has_ipv6=has_ipv6,
+        has_dualstack_ipv6=has_dual,
+        default_timeout=socket.getdefaulttimeout(),
+        hostname=socket.gethostname(),
+    )
+```
+
+`has_dualstack_ipv6()` は OS レベルで IPv6 デュアルスタックが使えるかを確認する。
+WSL2 環境では `False` になることがある。`OSError` でガードしてポータブルに書く。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `socket` モジュールは nene2-python のミドルウェアや認証と直接の接点はない。
+  DNS 解決やホスト情報を FastAPI エンドポイントで提供する形で統合した。
+- 戻り値は `@dataclass(frozen=True, slots=True)` で定義し、
+  FastAPI が Pydantic v2 経由で JSON シリアライズする。
+  ネストした dataclass (`DnsResult.addresses: list[AddressInfo]`) も問題なく動作した。
+- HTTP 境界での入力制約（`host: str = Field(..., max_length=253)`, `port: int = Field(80, ge=1, le=65535)`）
+  は Pydantic Body で完結し、DNS ルックアップに不正入力が渡らないよう保護した。
+- `getaddrinfo` が失敗する未知ホストに対しては `socket.gaierror` を捕捉して空リストを返す
+  設計にした。例外を 500 にせず意味のあるレスポンスを返す nene2 の「薄い HTTP 層」の原則に合致する。
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+FastAPI の Hello World を書けるようになった段階。
+`socket` が標準ライブラリにあることは知っているが、
+「なぜ TCP と UDP で動きが違うのか」の理解が浅い。
+
+**ドキュメント理解**: `socket.getaddrinfo` の戻り値型が複雑で、Python 公式ドキュメントだけでは
+タプルの構造を読み取りにくい。サンプルコードと「`info[4]` はアドレスタプルで AF_INET は `(host, port)`」
+という図解があると理解が一段上がる。  
+**事故リスク**: 中。`sendall(b"")` で `recv()` がブロックするというF-1の罠は
+初心者には気づきにくい。「空文字の扱い」は必ずコメントかドキュメントに記載が必要。  
+**規約の使いやすさ**: `socketpair` → `sendall` → `recv` のシーケンスは直感的で、
+一度理解すれば机械的に書ける。`finally` でクローズを忘れない規約（または `with` 文）を教えれば問題ない。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+既存コードを見て `socketpair` を使いこなせるが、深い仕組みはブラックボックスにしがち。
+
+**コピペ可能性**: `tcp_echo_pair` のコードをそのままコピーして使える。
+ただし「空メッセージのガード」を知らずに削除するリスクがある（F-1 の再発）。  
+**拡張時の罠**: `socketpair` を `connect` に置き換えて外部サービスに向けるとき、
+タイムアウトを設定しないまま本番投入するリスクが高い。
+`sock.settimeout(seconds)` を必ず設定することをコードコメントかテンプレートで強制すべき。  
+**セキュリティ的な事故リスク**: 低。`socket` そのものは低レベル API のため、
+使い方を誤っても金銭的損害には直結しにくい。ただし `getaddrinfo` を SSRF の起点にするパターンには注意が必要。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+REST API の呼び出し側として実装経験があり、
+「なぜこのエンドポイントが `message: str` だけを受け取るのか」が分かりやすい API を好む。
+
+**エラーレスポンスの質**: `host` が 254 文字以上のとき 422 + `detail` の Pydantic エラーが返り、
+クライアントにとって扱いやすい。`gaierror` (DNS 失敗) を 200 + 空 `addresses` で返す設計は
+クライアントがエラーを区別する必要がなく良い DX 判断。  
+**Python 固有概念の学習コスト**: `socketpair` / `AF_UNIX` / `SOCK_STREAM` の意味は
+TypeScript 経験者には馴染みが薄い。エンドポイントの OpenAPI description で目的を説明している点は助かる。  
+**事故リスク**: 低。このエンドポイント群は読み取り系で副作用がないため、
+フロントエンド寄り開発者が誤用してシステムを壊すリスクは小さい。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+`socket` モジュールは使ったことがあるが、`socketpair` は「そんな API があったのか」という反応。
+
+**他フレームワークとの差異**: Django では `socket` をユーザーランドに公開するエンドポイントを
+作ることはほとんどない。このFTで示したパターン（ヘルスチェックや環境情報エンドポイントへの応用）は
+実用性が高く「使える設計」と評価できる。  
+**nene2-python の薄さへの評価**: `create_app()` ファクトリパターン・`APIRouter` の分離が
+このサイズ（ファイル3つ）でも一貫して適用されており、「小さくても本番と同じ構造」を実証している。
+チームで使うときのテンプレートとして説得力がある。  
+**本番投入可能性**: ソケット操作系の本番エンドポイントは認証保護が必須。
+このFTでは `BearerTokenMiddleware` を使っていないが、実運用では認証ミドルウェアを被せること。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+チームメンバーが F-1 の罠を再現しないかを重点確認する。
+
+**コードレビューチェックポイント**:
+- [x] 空メッセージの早期リターンがあるか（F-1 対策）
+- [x] `socketpair` の `finally` でクローズ漏れがないか
+- [x] `gaierror` を握りつぶさず意味のある値を返しているか
+- [ ] 実運用では `sock.settimeout()` でハングを防いでいるか（このFTには外部接続なし）
+- [x] ユーザー入力 `host` / `message` に長さ制限があるか（Pydantic Field で保護済み）
+
+**チームでの安全な共有パターン**: 空入力ガードとタイムアウト設定をセットにした
+`safe_socket_connect()` ヘルパーをプロジェクト共通ユーティリティとして提供すると事故が減る。  
+**ツール追加の必要性**: ruff の `S` ルールが `socket.create_connection` に `timeout=None` を
+flagging しないため、コードレビューで明示的に確認が必要。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md の「Security first」「薄い HTTP 層」「AI-readable」との整合を確認する。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 高  
+
+- `host` の長さ制限（253 chars = DNS 最大長）と `port` の範囲制限（1〜65535）が Pydantic で宣言的に実装されており、検証を忘れるリスクがない。
+- `gaierror` の捕捉と空リスト返却は、例外を「500 にする」のではなく「意味のあるレスポンスにする」nene2 の方針に沿っている。
+- `match` 文による型安全な分岐は `cast()` / `# type: ignore` を使わず mypy --strict をパスしており、CLAUDE.md「型安全ポリシー」を遵守している。
+- F-1（空メッセージブロック）の修正コメント「sendall(b"") は TCP ではデータを送出しないため server.recv がブロックする」は、「WHY が非自明な場合のみコメント」のポリシーに準拠した正当なコメント。
+
+**設計上の負債・ドキュメント不足**: なし  
+**Follow-up Issue 候補**: なし
+
+---
+
+## Follow-up Issues
+
+なし — 今回発見した摩擦点（F-1, F-2）はサンドボックス内で即時修正済み。
+
+---
+
+## まとめ
+
+`socket` モジュールは低レベル API ながら、
+`socketpair()` を使うことで外部ネットワーク依存なしにインプロセスでエコーテストを書ける点が発見だった。
+`getaddrinfo` の戻り値型（F-2）は typeshed の制約で mypy が `str | int` を報告するが、
+`match` 文のパターンマッチングで `cast()` なしに解決できた。
+`sendall(b"")` が TCP ブロックの原因になる点（F-1）は典型的な「空入力の罠」として記録した。
+
+次のFT194 は 194 % 3 = 2 → セキュリティ診断なし、194 % 4 = 2 → クラッカーペンテストなし。
+ネットワーク系の継続として `ssl` モジュール（TLS コンテキスト・自己署名証明書・HTTPS クライアント）が候補。

nene2_python-1.8.66/docs/field-trials/2026-05-field-trial-194.md

@@ -0,0 +1,302 @@
+# FT194: ipaddress モジュール — IPv4/IPv6 解析・CIDR 計算・SSRF 防御パターン
+
+**日付**: 2026-05-21
+**テーマ**: Python `ipaddress` モジュールを使ったアドレス解析・ネットワーク計算・SSRF 防御パターンの実装と検証
+**セキュリティ診断**: なし（194 % 3 = 2）
+**クラッカーペンテスト**: なし（194 % 4 = 2）
+
+---
+
+## 概要
+
+`ipaddress` モジュールは IPv4/IPv6 アドレス・ネットワークを型安全に扱う標準ライブラリ。
+FT193（socket）で DNS 解決の話が出たが、解決後の IP が安全かどうかを確認するのに `ipaddress` は不可欠。
+FT184（urllib.request SSRF 防御）で使ったパターンの理論的基盤となるモジュールを正面から検証する。
+
+主要ユースケース:
+- DNS 解決後 IP の SSRF 安全性チェック（AWS メタデータ `169.254.169.254` 等のブロック）
+- CIDR ネットワーク計算（ホスト数・アドレス範囲）
+- IP バージョン・分類フラグの判定（private / loopback / link-local / multicast）
+- IP 範囲列挙（監査・ログ用途）
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft194-ipaddress/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `parse_address(ip_str)` | IPv4/IPv6 アドレスを解析。バージョン・分類フラグ全量を返す |
+| `parse_network(cidr)` | CIDR 表記を解析。`strict=False` でホストビット許容 |
+| `ssrf_safety_check(ip_str)` | DNS 解決後 IP が SSRF に悪用されないか確認。理由コードも返す |
+| `cidr_contains(cidr, ip_str)` | IP が CIDR 範囲内にあるか。IPv4/IPv6 バージョン不一致は安全に `False` |
+| `ip_range(start, end)` | 範囲内 IP を最大 100 件列挙。超過時は `truncated=True` |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/ipaddress/parse` | IP アドレス解析（フィールドバリデータで不正 IP を 422 返却） |
+| POST | `/ipaddress/network` | CIDR ネットワーク解析 |
+| POST | `/ipaddress/ssrf-check` | SSRF 安全性チェック |
+| POST | `/ipaddress/contains` | CIDR 包含チェック |
+| POST | `/ipaddress/range` | IP 範囲列挙 |
+
+---
+
+## テスト結果
+
+**42 passed**
+
+```
+42 passed in 0.32s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `IPv4Network.num_hosts` が typeshed 未定義（深刻度: 低）
+
+**事象**: `net.num_hosts` を呼ぶと mypy が
+`Item "IPv4Network" of "IPv4Network | IPv6Network" has no attribute "num_hosts"` を報告した。
+
+**原因**: Python 標準ライブラリの `ipaddress` モジュールには `num_hosts` プロパティが存在するが、
+typeshed の `IPv4Network` / `IPv6Network` スタブには宣言されていない（`_BaseNetwork` に定義されているが継承スタブが未整備）。
+
+**対応**: `num_hosts` を使わず、`prefixlen` と `max_prefixlen` から手動計算する。
+
+```python
+# typeshed に num_hosts が未定義のため手動計算
+# /31・/127（ポイントツーポイント）と /32・/128（ホストルート）は全アドレスが使用可能
+if net.prefixlen >= net.max_prefixlen - 1:
+    num_hosts = net.num_addresses
+else:
+    num_hosts = net.num_addresses - 2
+```
+
+### F-2: Python 3.11+ で `127.0.0.1.is_private` が `True` に変更（深刻度: 低）
+
+**事象**: `parse_address("127.0.0.1")` の結果に `is_private=True` が返り、
+`assert result.is_private is False` のテストが失敗した。
+
+**原因**: Python 3.11 で `ipaddress` モジュールの `is_private` の定義が拡張された。
+`127.0.0.0/8`（ループバック）が `is_private=True` を返すように変更された（RFC 1918 の厳密な解釈から RFC 5735 準拠の解釈へ）。
+
+**対応**: テストから `is_private=False` の仮定を削除し、`is_global=False` のみを確認。
+
+```python
+def test_ipv4_loopback(self) -> None:
+    result = parse_address("127.0.0.1")
+    assert result.is_loopback is True
+    # Python 3.11+ では 127.0.0.0/8 が is_private=True を返す仕様変更
+    assert result.is_global is False
+```
+
+SSRF チェックの `ssrf_safety_check` は `is_loopback` を先にチェックするため影響なし。
+
+### F-3: `ip_range` の `ValueError` が HTTP 500 になる問題（深刻度: 低）
+
+**事象**: `ip_range("10.0.0.10", "10.0.0.1")` で `ValueError` が発生するが、
+エンドポイントは 422 を返すべきなのに 500 になっていた。
+
+**原因**: Pydantic の Body バリデーションは `start` / `end` を個別に型チェックするが、
+「end >= start」という相関制約は Pydantic では検出できない。
+`ip_range` から投げられた `ValueError` は FastAPI のデフォルト動作では 500 になる。
+
+**対応**: エンドポイントで `ValueError` を捕捉して `HTTPException(status_code=422)` に変換。
+
+```python
+@router.post("/ipaddress/range")
+def range_endpoint(body: RangeBody) -> RangeResult:
+    try:
+        return ip_range(body.start, body.end)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+```
+
+---
+
+## 観察点
+
+### 観察1: `ssrf_safety_check` — SSRF 防御の「セカンドライン」パターン
+
+```python
+def ssrf_safety_check(ip_str: str) -> SafetyCheck:
+    addr = ipaddress.ip_address(ip_str)
+    if addr.is_loopback:
+        return SafetyCheck(address=str(addr), is_safe=False, reason="loopback")
+    if addr.is_link_local:
+        return SafetyCheck(address=str(addr), is_safe=False, reason="link_local")
+    if addr.is_private:
+        return SafetyCheck(address=str(addr), is_safe=False, reason="private")
+    ...
+```
+
+SSRF 対策は2層構造が安全:
+1. ファーストライン: URL/ホスト名をドメインパターンで拒否（`localhost`, `*.internal` 等）
+2. セカンドライン: DNS 解決後に IP を `ssrf_safety_check` で確認
+
+FT184（urllib.request）でカバーしたファーストラインと組み合わせることで DNS Rebinding 攻撃にも対応できる。
+`169.254.169.254`（AWS EC2 メタデータ）が `is_link_local=True` で確実にブロックされることを確認した。
+
+### 観察2: `cidr_contains` で `match` 文を使った型安全な分岐
+
+```python
+match (net, addr):
+    case (ipaddress.IPv4Network() as net4, ipaddress.IPv4Address() as addr4):
+        contains = addr4 in net4
+    case (ipaddress.IPv6Network() as net6, ipaddress.IPv6Address() as addr6):
+        contains = addr6 in net6
+    case _:
+        contains = False
+```
+
+`IPv4Address in IPv4Network` は OK だが `IPv6Address in IPv4Network` は `TypeError`。
+`match` で型を同時絞り込みしてバージョン不一致を型レベルで排除できる。
+このパターンは FT193（socket）の `getaddrinfo` 型絞り込みと同じアプローチ。
+
+### 観察3: `@field_validator` で HTTP 境界の IP 形式バリデーション
+
+```python
+class ParseAddressBody(BaseModel):
+    address: str = Field(..., max_length=45)
+
+    @field_validator("address")
+    @classmethod
+    def validate_ip(cls, v: str) -> str:
+        try:
+            ipaddress.ip_address(v)
+        except ValueError as exc:
+            raise ValueError("invalid IP address") from exc
+        return v
+```
+
+Pydantic の `str` フィールドはデフォルトで IP 形式を検証しない。
+`@field_validator` で `ipaddress.ip_address()` を呼ぶことで、
+HTTP 境界で不正 IP を 422 として弾ける。
+`ssrf_safety_check` の入力にはあえてバリデータを付けず、
+内部で `invalid_address` を返す設計にした（サービスの挙動が安定する）。
+
+### 観察4: `ip_range` の `match start:` パターン
+
+```python
+match start:
+    case ipaddress.IPv4Address():
+        addresses = [str(ipaddress.IPv4Address(int(start) + i)) for i in range(count)]
+    case ipaddress.IPv6Address():
+        addresses = [str(ipaddress.IPv6Address(int(start) + i)) for i in range(count)]
+```
+
+`ip_address()` の返り値は `IPv4Address | IPv6Address`。
+`ipaddress.ip_address(int(start) + i)` を使うと大きい整数が IPv4 範囲外で IPv6 になるリスクがある。
+`match` でバージョンを先に絞り込んで `IPv4Address(int)` / `IPv6Address(int)` を直接使うことで
+バージョン保存が型レベルで保証される。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `ipaddress` モジュールは nene2 のミドルウェアと直接の接点はないが、
+  `ssrf_safety_check` は `nene2.http` や `nene2.middleware` が提供する SSRF 防御ユーティリティの候補。
+- FT184（urllib.request）の SSRF 防御実装では `ipaddress.ip_address(resolved_ip)` をチェックする
+  コードが必要になる。今回実装した `ssrf_safety_check` はその実装の参照として使える。
+- HTTP 境界のバリデーションで `@field_validator` + `ipaddress.ip_address()` の組み合わせは
+  Pydantic BodyModel に組み込む標準パターンとして CLAUDE.md への追記候補。
+- `ip_range` の `ValueError` → 422 変換は、ドメインロジックの入力エラーをどう HTTP 境界で扱うかの好例。
+  `ValidationException` を使う nene2 パターンとの整合も検討余地がある。
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+SSRF という言葉を聞いたことはあるが、「なぜ IP アドレスをコードでチェックするのか」がまだ腑に落ちていない段階。
+
+**ドキュメント理解**: `ipaddress.ip_address()` と `ipaddress.ip_network()` の使い方は Python 公式ドキュメントが丁寧で理解しやすい。
+ただし「`is_private` の定義が Python 3.11 で変わった」（F-2）はドキュメントに小さくしか書かれておらず、テストが壊れて初めて気づくことが多い。
+バージョン間の差異を解説する how-to ページがあると助かる。  
+**事故リスク**: 中。`is_private` と `is_loopback` を個別にチェックしなければ `127.0.0.1` が抜けるリスクがある（3.11 以前の Python では）。`ssrf_safety_check` のような一元的な関数でラップするパターンを教えると安全。  
+**規約の使いやすさ**: `ipaddress.ip_address(str)` → `addr.is_private` のシーケンスは直感的で習得しやすい。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+SSRF チェックを実装したことがあり、`if ip.startswith("192.168")` のような文字列比較でやっていた可能性がある。
+
+**コピペ可能性**: `ssrf_safety_check` のコードをそのままコピーできる品質。ただし `is_loopback` と `is_private` の順序を入れ替えると動作が変わる（3.11 以前）ことに気づきにくい。  
+**拡張時の罠**: 「IPv4 しかチェックしていない」まま IPv6 対応の要件が来たとき、`is_link_local` の `fe80::/10` などが見落とされやすい。IPv4 と IPv6 を同時にカバーするこの実装は参照価値が高い。  
+**セキュリティ的な事故リスク**: 中。`ssrf_safety_check` を使わずに自前チェックを書くと脆弱になる可能性がある。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+IP アドレスの概念は知っているが `is_link_local` や CIDR 表記が馴染み薄い。
+
+**エラーレスポンスの質**: 不正 IP に対して `@field_validator` が 422 + `detail: "invalid IP address"` を返すため、クライアント実装が容易。`ssrf_safety_check` が `is_safe=false, reason="link_local"` を返す設計は、クライアント側でブロック理由を表示できて良い。  
+**Python 固有概念の学習コスト**: `ipaddress.ip_network("192.168.1.0/24", strict=False)` の `strict=False` の意味は Python 固有。「ホストビットが立っていても正規化して受け入れる」説明が必要。  
+**事故リスク**: 低。このエンドポイントは副作用がない解析系。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+IP 検証を `django.core.validators.validate_ipv4_address` で実装してきた経験がある。
+
+**他フレームワークとの差異**: Django の `InetAddressField` (django-netfields) より明示的だが、標準ライブラリだけでここまでできる点は評価が高い。`@field_validator` + `ipaddress` の組み合わせは Django フォームのカスタムバリデータと発想が同じで移行コストが低い。  
+**nene2-python の薄さへの評価**: SSRF チェックがミドルウェアに組み込まれず「ユースケース層で明示的に呼ぶ」設計は、「魔法を排除して可視化する」nene2 の方針と整合している。どのエンドポイントで SSRF チェックをしているかコードレビューで確認しやすい。  
+**本番投入可能性**: `ssrf_safety_check` をユーティリティとして共通化し、外部 URL を受け取るエンドポイントすべてで使う運用が望ましい。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+DNS Rebinding 攻撃を知っており、「SSRF チェックは DNS 解決後に行う」の原則を重視している。
+
+**コードレビューチェックポイント**:
+- [x] `ssrf_safety_check` を DNS 解決後に呼んでいるか（解決前に呼んでも意味がない）
+- [x] `is_loopback` の前に `is_link_local` を確認しているか（順序依存なし、全フラグをカバー）
+- [x] IPv6 の `::1` も `is_loopback=True` で弾けているか
+- [x] `169.254.169.254`（AWS メタデータ）が `is_link_local` でブロックされるか
+- [x] バージョン不一致（IPv4 CIDR + IPv6 アドレス）が型安全に `False` を返すか
+
+**チームでの安全な共有パターン**: `ssrf_safety_check` を `nene2.http.utils` に追加して、外部 URL を受け取る全エンドポイントで import を強制する仕組みが良い。今後の FT で nene2 コアへの昇格を検討。  
+**ツール追加の必要性**: ruff では「SSRF チェックなしで外部 URL を fetch している」パターンを静的に検出できない。コードレビューガイドラインへの追記が実用的。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md 「Security first」「初心者でも安全な API」との整合を確認する。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 高  
+
+- HTTP 境界で `@field_validator` + `ipaddress.ip_address()` を使って不正 IP を 422 に変換している。初心者がコピーしても「文字列のまま使う」事故を防げる。
+- `ssrf_safety_check` が `loopback` → `link_local` → `private` の順で明示的にチェックするため、SSRF 防御の穴が読みやすい。「何をチェックしているか」が可視化されている。
+- F-2（Python 3.11 の `is_private` 変更）は CLAUDE.md に追記すべき知見。`is_loopback` と `is_private` を別々に扱う必要性と Python バージョン間の差異を記録する。
+- F-3（`ValueError` → 422 変換）は nene2 の `ValidationException` パターンとの整合を今後検討すべき。`HTTPException(status_code=422)` は簡便だが `Problem Details` 形式ではない。
+
+**設計上の負債**: `ssrf_safety_check` を nene2 コア (`nene2.http.safety` 等) に昇格させる候補。FT184 で urllib.request に使い、今回で ipaddress との組み合わせが確認できた。  
+**Follow-up Issue 候補**: `ssrf_safety_check` の nene2 コア昇格（中優先度）
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `ssrf_safety_check` ユーティリティを nene2 コアに昇格させる | feat |
+| 低 | Python 3.11+ の `is_private` 仕様変更を docs/how-to に記録 | docs |
+
+※ nene2 コア昇格は FT 単体の PR 内には収めず、別途 Issue/PR で対応する。
+
+---
+
+## まとめ
+
+`ipaddress` モジュールは SSRF 防御の実装基盤として非常に実用的だった。
+`169.254.169.254`（AWS メタデータエンドポイント）が `is_link_local=True` で確実にブロックされることを実証し、
+loopback / private / link-local / reserved の全フラグを組み合わせたチェック関数のリファレンス実装を得た。
+
+技術的な発見として、Python 3.11 の `is_private` 定義変更（F-2）と typeshed の `num_hosts` 未定義（F-1）は
+バージョン依存のはまりポイントとして記録価値がある。
+
+次の FT195 は 195 % 3 = 0 → **セキュリティ診断あり**、195 % 4 = 3 → クラッカーペンテストなし。
+テーマ候補: `ssl` モジュール（TLS コンテキスト・証明書検証）または `http.client`（低レベル HTTP クライアント）。

{nene2_python-1.8.64 → nene2_python-1.8.66}/docs/field-trials/INDEX.md

@@ -226,14 +226,16 @@
 | [FT190](2026-05-field-trial-190.md) | multiprocessing モジュール — プロセスベース並行処理・共有状態・プロセスプール | | |
 | [FT191](2026-05-field-trial-191.md) | concurrent.futures モジュール — ThreadPoolExecutor / ProcessPoolExecutor / Future | | |
 | [FT192](2026-05-field-trial-192.md) | asyncio モジュール — コルーチン・タスク・Lock・Event・Semaphore・Queue・TaskGroup | 🔒🔍 | |
+| [FT193](2026-05-field-trial-193.md) | socket モジュール — TCP/UDP socketpair・DNS 解決・ソケットオプション | | |
+| [FT194](2026-05-field-trial-194.md) | ipaddress モジュール — IPv4/IPv6 解析・CIDR 計算・SSRF 防御パターン | | |
 
 ---
 
 ## セキュリティ診断実施済み一覧（🔒）
 
-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, 180, 183, 186, 189
+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, 180, 183, 186, 189, 192
 
-合計: **63件**（189 FT 中 約 33%）
+合計: **64件**（194 FT 中 約 33%）
 
 ## クラッカーペンテスト実施済み一覧（🔍）
 
@@ -241,4 +243,4 @@ FT172, FT176, FT180, FT184, FT188, FT192
 
 ---
 
-*最終更新: 2026-05-21 (FT192 / v1.8.64)*
+*最終更新: 2026-05-21 (FT194 / v1.8.66)*