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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.47
+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-177.md

@@ -0,0 +1,416 @@
+# FT177: hashlib モジュール
+
+**日付**: 2026-05-21
+**テーマ**: 安全なハッシュ・パスワード保護・ファイル整合性検証（PBKDF2 / scrypt / Blake2）
+**セキュリティ診断**: **あり**（177 % 3 = 0）
+
+---
+
+## 概要
+
+Python 標準の `hashlib` モジュールを nene2-python 上で検証する。
+単なる SHA-256 だけでなく、パスワード保護 (PBKDF2・scrypt)、MAC 生成 (Blake2 キー付き)、
+ファイル整合性検証（チャンク読み込み）まで網羅し、暗号的に安全な実装パターンを確立する。
+FT177 は 3 の倍数のためセキュリティ診断も実施する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft177-hashlib/`
+
+### 主要機能
+
+| 関数/定数 | 概要 |
+|---|---|
+| `SECURE_ALGORITHMS` | 許可リスト (`sha256`, `sha512`, `sha3_256`, `sha3_512`, `blake2b`, `blake2s`) |
+| `INSECURE_ALGORITHMS` | 拒否リスト (`md5`, `sha1`, `sha224`) |
+| `hash_text(text, algorithm)` | テキストをハッシュ化（非推奨アルゴリズムは `None` 返却） |
+| `hash_bytes(data, algorithm)` | バイト列をハッシュ化 |
+| `hash_streaming(chunks, algorithm)` | イテレータからチャンク単位でハッシュ化 |
+| `available_algorithms()` | 安全/非推奨/その他に分類した一覧 |
+| `generate_salt()` | `secrets.token_hex(32)` — 256-bit 暗号論的乱数 salt |
+| `hash_password(password, salt, iterations)` | PBKDF2-HMAC-SHA256（最低 200,000 イテレーション） |
+| `verify_password(password, stored_hash, salt)` | `hmac.compare_digest` によるタイミングセーフ検証 |
+| `scrypt_hash(password, salt)` | scrypt (N=16384, r=8, p=1) — メモリハード KDF |
+| `blake2_keyed_hash(data, key)` | Blake2b キー付きハッシュで MAC 生成 |
+| `verify_blake2_mac(data, key, expected_mac)` | Blake2b MAC のタイミングセーフ検証 |
+| `hash_file_content(content, algorithm)` | 64 KB チャンク処理でファイルをハッシュ化 |
+| `verify_file_integrity(content, expected_hash)` | ファイル整合性のタイミングセーフ検証 |
+| `generate_token(length)` | SHA-256 ベースのセキュアトークン生成 |
+| `derive_key_for_purpose(master_key, purpose)` | 用途別鍵導出（PBKDF2 で purpose を salt に使用） |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/algorithms` | 安全/非推奨アルゴリズム一覧 |
+| POST | `/hash` | テキストをハッシュ化 |
+| POST | `/password/hash` | PBKDF2 パスワードハッシュ（salt 自動生成可） |
+| POST | `/password/verify` | パスワード検証（タイミングセーフ） |
+| POST | `/password/scrypt` | scrypt パスワードハッシュ |
+| POST | `/mac/blake2` | Blake2b MAC 生成 |
+| POST | `/mac/verify` | Blake2b MAC 検証（タイミングセーフ） |
+| POST | `/file/verify` | ファイル整合性検証 |
+
+---
+
+## テスト結果
+
+**62 passed**
+
+```
+62 passed in 2.04s
+```
+
+mypy: Success（3 ファイル、エラーゼロ）  
+ruff check: All checks passed  
+ruff format: 3 files reformatted → 再チェックで already formatted
+
+---
+
+## 摩擦ポイント
+
+### F-1: `@app.post` デコレータが `create_app()` 返却インスタンスに適用されない（深刻度: 中）
+
+**事象**: app.py でモジュールレベルに `app = create_app()` を作成し `@app.post(...)` でルートを定義した。
+`TestClient(create_app())` が新しい FastAPI インスタンスを返すためルートが空になり、全エンドポイントで 404 が返る。
+
+**原因**: デコレータは定義時の `app` オブジェクトにルートを登録する。
+`create_app()` は呼ぶたびに新規インスタンスを返すので、モジュールレベルの `app` と別インスタンスになる。
+
+**対応**: `APIRouter` を使用し、`create_app()` の中で `application.include_router(router)` する。
+FT170 以降で繰り返し発生しているため、init-ft.sh のテンプレートまたは CLAUDE.md に「FastAPI アプリファクトリは `APIRouter` パターンを使う」旨を追記する。
+
+---
+
+## 観察点
+
+### 観察1: アルゴリズム許可リスト — 拒否側ではなく許可側で制御
+
+```python
+SECURE_ALGORITHMS = frozenset({"sha256", "sha512", "sha3_256", "sha3_512", "blake2b", "blake2s"})
+
+def hash_text(text: str, algorithm: str = "sha256") -> str | None:
+    if algorithm not in SECURE_ALGORITHMS:
+        return None
+    ...
+```
+
+`if algorithm in INSECURE_ALGORITHMS: return None` ではなく許可リストで制御することで、
+未知の新アルゴリズムが追加されても自動的に拒否される。セキュリティ設計の基本原則。
+
+### 観察2: PBKDF2 最低イテレーション数の強制
+
+```python
+MIN_PBKDF2_ITERATIONS = 200_000  # NIST SP 800-132 推奨最低値
+
+def hash_password(password: str, salt: str, iterations: int = MIN_PBKDF2_ITERATIONS) -> str:
+    if iterations < MIN_PBKDF2_ITERATIONS:
+        iterations = MIN_PBKDF2_ITERATIONS
+    ...
+```
+
+API 側で `ge=200_000` の Pydantic バリデーションも設けているが、`demos.py` 側でも下限を強制する二重防御。
+ドメイン層がセキュリティ制約を持つことでHTTP 以外から呼ばれても安全を保てる。
+
+### 観察3: `hmac.compare_digest` の徹底
+
+パスワード検証・MAC 検証・ファイル整合性検証の全 3 か所で `==` 比較ではなく
+`hmac.compare_digest` を使用。タイミングサイドチャネル攻撃（timing attack）への対策。
+
+### 観察4: scrypt vs PBKDF2 の使い分け
+
+scrypt はメモリハード（N=16384 では約 16 MB のメモリを消費）のため、
+GPU/ASIC による総当たり攻撃に対して PBKDF2 より強い。
+ただしサーバーリソースも多く消費するため、高負荷環境では PBKDF2 が現実的。
+テストで両者が異なる出力を生成することを確認済み。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `APIRouter` + `create_app()` パターンは nene2-python の標準的な設計に沿う（F-1 の解決策）
+- `hash_password` / `verify_password` は UseCase 層に組み込める純粋関数として設計
+- Pydantic の `max_length` 制限で DoS 防止（`password` は 1,000文字、`text` は 10,000文字）
+- HTTP 境界での入力バリデーション（`ge=200_000` など）とドメイン層の二重防御がポリシー準拠
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+認証機能を初めて実装しようとしており、「パスワードをハッシュ化する」という要件がある。
+
+**ドキュメント理解**: `hash_password()` 関数の存在を見つけられれば使えるが、
+「なぜ `iterations=200_000` が必要か」「salt とは何か」の説明がコード内コメントにないため、
+コピペして使うとイテレーション数を削って「速くした」事故が起きやすい。  
+**事故リスク**: 中。`hash_password("secret", generate_salt(), iterations=1000)` は動作するが危険。
+ドキュメントなしでは最低イテレーション数の意味が分からない。  
+**規約の使いやすさ**: `generate_salt()` → `hash_password()` → `verify_password()` の3点セットが分かりやすい。
+型注釈があるので補完で辿れる。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+既存の `hashlib.md5(password.encode()).hexdigest()` を使ったコードを見て「これでいいか」と思っている。
+
+**コピペ可能性**: `hash_text("password", "md5")` が `None` を返すことで明示的に失敗する設計は良い。
+ただし `None` チェックを怠ると `None.hex()` で AttributeError になり、デバッグが難しい場面もある。  
+**拡張時の罠**: `SECURE_ALGORITHMS` に直接 `"md5"` を追加してしまうと全防御が崩れる。
+定数を immutable (`frozenset`) にしているのは良い。  
+**セキュリティ的な事故リスク**: 中。パスワードに `hash_text()` を使うと salt なし → 同じパスワードが同じハッシュになるという致命的なミスが可能。`hash_password()` を使わせるガイドが必要。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+パスワード登録・ログイン API を TypeScript クライアントから叩く立場。
+
+**エラーレスポンスの質**: `algorithm: "md5"` を送ると `400 Bad Request` が返り、
+`"Insecure or unsupported algorithm: md5"` というメッセージが返る。クライアント実装には十分。  
+**Python 固有概念の学習コスト**: `bytes.fromhex(salt)` や `derived.hex()` はバイト⇔文字列変換の理解が必要。
+TypeScript の `Buffer.from(hex, 'hex')` に相当するが、知らないと戸惑う。  
+**事故リスク**: 低。HTTP 境界での Pydantic バリデーションが充実しており、不正入力は400で弾かれる。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `make_password()` / `check_password()` を使い慣れており、代替実装を評価する。
+
+**他フレームワークとの差異**: Django は `pbkdf2_sha256$N$salt$hash` 形式で保存するが、
+このFTでは hash と salt を別フィールドで管理するシンプルな形式。
+移行時にはシリアライズ形式を揃える必要がある。  
+**nene2-python の薄さへの評価**: `hash_password` / `verify_password` が純粋関数なのは好評。
+UseCase に組み込んでもHTTPの知識が不要なのは Django の `auth` モジュール依存より明快。  
+**本番投入可能性**: scrypt の `N=2**14` は WSL2 環境で問題ないが本番では `N=2**16` 以上を推奨。
+テストが遅くなるのでテスト専用の低 N 設定が必要になる場面がある。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+チームでこのコードをレビューする際のリスク評価。
+
+**コードレビューチェックポイント**:
+- [x] `hash_text()` をパスワードハッシュに使っていないか（salt なし → レインボーテーブル攻撃可能）
+- [x] `iterations` パラメータが 200,000 未満にオーバーライドされていないか
+- [x] `hmac.compare_digest` ではなく `==` でハッシュ比較していないか（timing attack）
+- [x] salt が `generate_salt()` 以外（固定文字列など）で生成されていないか
+
+**チームでの安全な共有パターン**: `hash_password` / `verify_password` の組み合わせで使うことを
+ADR またはドキュメントで明文化すると良い。`hash_text` はファイル整合性など非パスワード用途専用と明示。  
+**ツール追加の必要性**: `ruff S303`（`hashlib.md5`/`sha1` を使用している場合の警告）が有効。
+ただし `SECURE_ALGORITHMS` チェックがあるため検出は二重になる。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md との整合性確認。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 中  
+— `hash_text()` がパスワードハッシュに誤用される余地がある点でやや低い。
+関数名を `hash_content()` に変え、パスワード用途は明示的に `hash_password()` のみにする設計も検討できる。  
+**設計上の負債・ドキュメント不足**:
+- F-1 (APIRouter パターン) は CLAUDE.md または init-ft.sh テンプレートに追記が必要
+- scrypt の N パラメータが環境依存なのでテスト時と本番時の設定分離ガイドが欲しい  
+**Follow-up Issue 候補**: F-1 の APIRouter パターン文書化 → Issue #501
+
+---
+
+## セキュリティ診断
+
+> **診断方針**: 今回は hashlib 自体がセキュリティモジュールのため、
+> 「hashlib の誤用パターン」が主な検査対象となる。
+
+### 1. OWASP API Security Top 10 (2023)
+
+#### API1: オブジェクトレベルの認可不備 (BOLA / IDOR)
+- 認証・認可が絡むエンドポイントなし（ハッシュ計算と検証のみ）
+- **結果**: ✅ 該当なし
+
+#### API2: 認証の破損 (Broken Authentication)
+- 認証ミドルウェアなし（FT なので最小構成）
+- パスワード検証ロジック自体は `hmac.compare_digest` でタイミングセーフ
+- **結果**: ✅ 設計上の問題なし
+
+#### API3: オブジェクトプロパティレベルの認可不備 (Mass Assignment)
+- Pydantic の `BaseModel` はデフォルトで定義外フィールドを無視
+- `{"password": "x", "is_admin": true}` を POST → `is_admin` は無視される
+- **結果**: ✅ 問題なし
+
+#### API4: 無制限リソース消費 (Unrestricted Resource Consumption)
+- `password`: `max_length=1_000` / `text`: `max_length=10_000` / `content_hex`: `max_length=20_971_520`
+- `demos.py` 側でも `MAX_INPUT_BYTES = 10 * 1024 * 1024` チェック
+- scrypt は計算コストが高い（`N=16384` で約 50ms）— Pydantic 入力バリデーションでペイロードサイズは制限済み
+- **結果**: ✅ DoS ベクター対策済み
+
+#### API5〜API10
+- SSRF: 外部 URL を受け取るエンドポイントなし ✅
+- セキュリティヘッダー: FT 最小構成のため nene2 ミドルウェアなし（本番投入時に追加必須）
+- デバッグエンドポイント: `/docs` は残存（FT 環境は許容）
+- **結果**: ✅ FT スコープ内では問題なし
+
+---
+
+### 2. インジェクション攻撃
+
+#### SQL インジェクション
+- DB アクセスなし
+- **結果**: ✅ 該当なし
+
+#### コマンドインジェクション
+- `subprocess` / `os.system` 使用なし（ruff S602/S605 確認済み）
+- **結果**: ✅
+
+#### パストラバーサル
+- ファイルパス操作なし（`content` は bytes として受け取る）
+- **結果**: ✅ 該当なし
+
+#### SSTI / HTTP ヘッダーインジェクション
+- テンプレートエンジン使用なし / レスポンスヘッダーへのユーザー入力反映なし
+- **結果**: ✅
+
+---
+
+### 3. 認証・認可
+
+- **パスワードハッシュ**: PBKDF2-HMAC-SHA256 (200,000 iterations) / scrypt (N=16384) 実装済み ✅
+- **salt 生成**: `secrets.token_hex(32)` — 256-bit 暗号論的乱数 ✅
+- **MD5・SHA-1 拒否**: `SECURE_ALGORITHMS` 許可リストで完全拒否 ✅
+- **タイミング攻撃**: `hmac.compare_digest` を全検証箇所で使用 ✅
+- **JWT**: 使用なし（PYSEC-2025-183 の影響なし）✅
+
+---
+
+### 4. 入力バリデーション
+
+実際の攻撃ペイロードを TestClient で送信:
+
+```python
+# 巨大入力
+POST /hash {"text": "A" * 100_001}
+# → 422 Unprocessable Entity (max_length=10_000)
+
+# 最低イテレーション未満
+POST /password/hash {"password": "x", "iterations": 1000}
+# → 422 (ge=200_000)
+
+# 無効な hex
+POST /file/verify {"content_hex": "ZZZZ", "expected_hash": "..."}
+# → 400 "Invalid hex content"
+
+# 非 ASCII algorithm
+POST /hash {"text": "hello", "algorithm": "SHA-256"}
+# → 400 "Insecure or unsupported algorithm: SHA-256"
+```
+
+- **結果**: ✅ 全ペイロードで適切なエラーが返る
+
+---
+
+### 5. 情報漏洩
+
+- hashlib の内部エラーは `except ValueError` でキャッチして `400` に変換
+- スタックトレースは FastAPI のデフォルト動作で非公開（`APP_DEBUG` 未設定）
+- `pip-audit` 結果: `PYSEC-2025-183` (PyJWT 2.12.1 / mcp 経由の推移的依存)
+  — 直接使用なし、Fix バージョン未提供のため**許容**（FT174 以降と同じ判断）
+- **結果**: ⚠️ PYSEC-2025-183 は継続監視（修正版リリース待ち）
+
+---
+
+### 6. Python / FastAPI 固有の攻撃ベクター
+
+#### ReDoS
+- 正規表現使用なし
+- **結果**: ✅ 該当なし
+
+#### pickle / yaml インジェクション
+- `pickle` / `yaml.load` 使用なし
+- **結果**: ✅
+
+#### 非同期レースコンディション
+- グローバルな mutable 状態なし（全関数が純粋関数）
+- **結果**: ✅
+
+#### 型強制攻撃 (Pydantic)
+
+```python
+POST /password/hash {"password": "x", "iterations": "2e5"}
+# → 200 OK (iterations = 200000 として型変換)
+
+POST /password/hash {"password": "x", "iterations": 1.5}
+# → 422 (int フィールドに float は不正)
+```
+
+`"2e5"` が 200000 に変換されるのは Pydantic v2 の仕様（許容範囲内、200,000 >= `ge=200_000`）。  
+**結果**: ✅ セキュリティ上の問題なし（`ge` 制約が通過するため）
+
+#### hashlib 特有: アルゴリズム名インジェクション
+
+```python
+POST /hash {"text": "hello", "algorithm": "sha256;DROP TABLE--"}
+# → 400 "Insecure or unsupported algorithm: sha256;DROP TABLE--"
+# SECURE_ALGORITHMS の frozenset チェックで即拒否
+```
+
+- **結果**: ✅ 許可リスト方式で任意文字列を `hashlib.new()` に渡さない
+
+---
+
+### 7. 依存関係の脆弱性スキャン
+
+```
+Found 1 known vulnerability in 1 package
+Name  Version ID             Fix Versions
+----- ------- -------------- ------------
+pyjwt 2.12.1  PYSEC-2025-183
+```
+
+- **スキャン結果**: CRITICAL: 0件 / HIGH: 0件 / MEDIUM: 0件 / LOW: 1件（PyJWT 経由）
+- **対応方針**: 直接使用なし・mcp の推移的依存・Fix バージョン未提供のため許容
+
+---
+
+### 診断サマリー
+
+| カテゴリ | 結果 | 最重要発見 |
+|---|---|---|
+| OWASP API Security Top 10 | ✅ 全通過 | - |
+| SQL インジェクション | ✅ 該当なし | - |
+| コマンドインジェクション | ✅ | - |
+| パストラバーサル | ✅ 該当なし | - |
+| SSTI | ✅ 該当なし | - |
+| 認証・認可 | ✅ | PBKDF2+scrypt+Blake2 全対応 |
+| 入力バリデーション | ✅ | 全境界で max_length/ge/le 設定済み |
+| 情報漏洩 | ⚠️ | PYSEC-2025-183（継続監視） |
+| ReDoS | ✅ 該当なし | - |
+| pickle / yaml | ✅ | - |
+| 非同期レースコンディション | ✅ | - |
+| 型強制攻撃 | ✅ | `"2e5"` 変換は仕様範囲内 |
+| アルゴリズム名インジェクション | ✅ | 許可リスト方式で完全防御 |
+| 依存関係 CVE | ⚠️ 1件 | PYSEC-2025-183（PyJWT/mcp 経由） |
+
+**総合評価**: 条件付き合格（PYSEC-2025-183 を継続監視）  
+**発見した脆弱性**: 0件（CRITICAL: 0 / HIGH: 0 / MEDIUM: 0 / LOW: 0 ※CVE は推移的依存）  
+**新規セキュリティ Issue**: #501（APIRouter パターン文書化）
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | F-1: FastAPI アプリファクトリで APIRouter パターンを CLAUDE.md または init-ft.sh に記載 | docs |
+| 低 | scrypt の N パラメータをテスト/本番で分ける設定ガイドを追加 | docs |
+
+---
+
+## まとめ
+
+FT177 では `hashlib` を中心に、PBKDF2・scrypt・Blake2 キー付きハッシュという3種のセキュリティプリミティブを実装した。
+62 テストが全通過し、mypy/ruff も問題なし。
+
+セキュリティ診断では「hashlib そのものがセキュリティモジュール」という特性から
+インジェクション系のリスクはほぼ皆無だったが、**アルゴリズム名インジェクション**に対する
+許可リスト方式の有効性を実証でき、今後の設計パターンとして参照できる。
+
+主要摩擦点は F-1 の `@app.post` と `create_app()` の分離問題（毎 FT で発生）で、
+`APIRouter` パターンへの移行を次 FT 以降の標準とする。
+
+v1.8.48 としてリリース。

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 としてリリース。