docs(PLAN54): base イメージに bao を入れ、コンテナから機密を読み書きする要求仕様と設計 (#169)

[takemi-ohama]

Summary

#169 の設計 Pull Request。実装は含まない（設計 PR のマージ後に実装用の作業ツリーで行う）。

• 要求仕様: issues/PLAN54_bao-in-container.md（受け入れ条件 10 件、非機能 3 項目、未決 1 件は設計で決定）
• 設計文書: issues/PLAN54_bao-in-container-design.md（機能 4 件、構成要素 12 件、決定 6 件、テスト設計 10 行、未確認 3 件）
• モード: standard（base イメージと起動経路の 2 領域にまたがる本番の振る舞いの追加）
• 関連: base イメージに OpenBao の CLI（bao）を入れ、起動中のコンテナから機密を取得・変更できるようにする #169（自動で閉じない）、docs/specifications/secret-backend.md、PLAN55 (devbase up が機密を 2 度注入し、サーバ backend では HTTP 往復が設計の想定の 2 倍になる #168) との順序は設計の「処理の流れ」に記載

決めたこと

issues/PLAN54_bao-in-container-design.md

• 決定 1: コンテナへ渡す資格情報は 1 時間の token だけにし、~/.vault-token に置く
• 決定 2: token の取り直しはホストの devbase env token が行い、コンテナには資格情報を置かない
• 決定 3: BAO_ADDR は環境変数で渡し、docker exec で書かない
• 決定 4: token の書き込みは up の [5/6] の後に置き、失敗しても up を倒さない
• 決定 5: bao は tar.gz を checksums.txt で検証して入れ、.deb は使わない
• 決定 6: 全端末の base イメージに bao を入れ、backend で入れ分けない

Test plan

設計の段階で確かめたこと:

• OpenBao v2.6.2 の GitHub Releases に openbao_2.6.2_linux_{amd64,arm64}.tar.gz と checksums.txt があり、tar.gz の中身は bao / CHANGELOG.md / LICENSE / README.md の 4 つ（gh api + tar -tzf、exit=0）
• bao 2.6.2 のバイナリに ~/.vault-token と BAO_TOKEN_PATH の文字列がある（strings）。実サーバでの確認はリリース後テスト
• containers/*/Dockerfile は 10 本。dev イメージ 9 本（base と派生 8 本）のうち USER を書く 8 本の最後が ubuntu、general は base を継ぐ。snapshot は root だが token の届け先ではない（grep -n ^USER、round 2 で数え直し）
• ドキュメント再構成の前後: 設計文書 平均文長 61.0 → 51.2 字 / 最長文 146 → 97 字 / 行数 263 → 271 / 章 9 → 9 / 結論の位置 5 → 3 行目。目安を超えた項目: 「決定の記録」52 行（目安 40）。理由: 6 件の決定を 1 節に集める形を保った。採らなかった直し方: 節を 2 つに分ける（決定の番号が節をまたぐ）
• 仕様の前後: 平均文長 59.7 → 56.9 字 / 最長文 209 → 209 字。理由: 受け入れ条件の「前提・操作・結果」を 1 項目として数えるため。採らなかった直し方: 3 行を別の項目に分ける（条件の対応が読めなくなる）

🤖 Generated with Claude Code

https://claude.ai/code/session_01S9okWVz1S7VGUsCQWVMhb3

[takemi-ohama]

🤖 cross-review | round 1 | kiro | REQUEST_CHANGES

設計 PR として決定の記録と処理の流れは整合しているが、要求仕様 PLAN54_bao-in-container.md の一部が「決定 1（token は環境変数 BAO_TOKEN ではなくファイル ~/.vault-token に置く）」の反映漏れで、BAO_TOKEN を環境変数で渡す旧方式のまま残っている。同一 PR 内の設計文書と矛盾し、実装者を旧方式へ誘導しうるので直したい。個別はインライン参照。

[takemi-ohama]

🤖 cross-review | round 1 | agy | REQUEST_CHANGES

PLAN54 の要求仕様書（issues/PLAN54_bao-in-container.md）および基本設計書（issues/PLAN54_bao-in-container-design.md）を精読しました。
決定 1（token の環境変数渡し廃止と ~/.vault-token 配置への変更）に伴う仕様書側の更新漏れ、クラス図・シーケンス図における ContainerTokenPusher の責務と呼び出しの不整合、既存 CLI 体系との不整合（env コマンドの -p オプション）、および既存テスト要件（cli.py の SUBCMD_MAP）への考慮漏れについて、計 7 点のインラインコメントで修正提案を記載しています。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 1)

対応件数: critical=0 / major=5 / minor=5 (合計 10 件。うち 2 件は同一箇所への重複指摘)
deferred: 0 件 / rejected: 0 件
commit: e52f559
CI: PENDING（push 直後。前コミット ac6e82f は全チェック success）

詳細

• 仕様 対象範囲 — BAO_TOKEN を渡す旧記述を ~/.vault-token に揃えた（取り消し線で旧記述を残す）
• 仕様 前提 7 — 渡さない対象を BAO_ADDR と token（~/.vault-token）に改め、用語表の bao の行も更新
• 仕様 受け入れ条件 6 / 同（agy） — 「~/.vault-token の token が切れている」へ
• 仕様 影響 — 「2 変数を渡す」→「BAO_ADDR を渡し ~/.vault-token を書く」
• 設計 cli.py の行 — SUBCMD_MAP / _NO_SECRET_INJECTION への登録と、それを固定する既存テストを明記
• 設計 構造 — token の取得と backend 判定を呼び出し側に置き、ContainerTokenPusher は docker だけを知る形に。クラス図・構成要素図・シーケンス図を揃えた
• 設計 env token の引数 — -p PROJECT を落とし、他の env サブコマンドと同じく実行時のディレクトリで対象を決める
• 設計 --print の挙動 — 処理の順を書き、--print はコンテナを見ずに終了コード 0 と明記
• 設計 docker exec の形 — 一時ファイル + mv -f の原子的置換にし、常に 0600 になる理由を記載

決定の記録（決定 1〜6）の見出しは変えていない。設計文書は 304 行（上限 500）。

[takemi-ohama]

🤖 cross-review | round 2 | kiro | COMMENT

設計・要求とも根拠の提示が丁寧で、参照している既存コード（_ensure_token/_token_expires_at @ lib/devbase/env/openbao.py、_apply_window_titles の付随処理パターン、_generate_compose_for の dev_environment、_NO_SECRET_INJECTION/SUBCMD_MAP @ cli.py、-p が store_true の真偽フラグである点、window_title.py の cp -p/_write_command/umask 077）は worktree で確認でき整合しています。実装は含まない設計 PR のため issue_token/_push_bao_token/container_token.py が未存在なのは前提どおり。

修正提案は 1 点のみ（インライン参照）:

• issues/PLAN54_bao-in-container-design.md:305 — containers/*/Dockerfile の本数と末尾 USER の記述が実態（10 本、うち snapshot は root で USER 行なし）と食い違う。$HOME 前提の根拠なので数と対象範囲を実態に合わせて修正。

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

修正が必要な指摘は 2 件です。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 2)

対応件数: critical=0 / major=2 / minor=1 (合計 3 件)
deferred: 0 件 / rejected: 0 件
commit: 8b47379
CI: SUCCESS（8b47379 で 5 チェックすべて success）

詳細

• 設計 docker exec の形（major / セキュリティ） — 固定名 .vault-token.tmp をやめ、mktemp で毎回新しく 0600 の一時ファイルを作ってから cat > → chmod 0600 → mv -f する契約に。既存ファイルへ書いて umask 077 が効かない件と並行実行の衝突を理由として本文に記載。シーケンス図・テスト設計 8 も揃えた
• 設計 env token の docker context（major / 正確性） — 処理の順に「接続先の解決」を足し、cmd_env_exec と同じ形（project.local.yml → choose_context → apply、--context NAME は _add_context_arg）で docker ps / docker exec の両方に効かせる。up は同一 process なので継承で足りる旨も書き直し。test_env_token.py でリモート context を固定
• 設計 Dockerfile の本数（minor / 正確性） — 10 本（dev イメージ 9 本、snapshot は root だが token の届け先ではない）に直し、PR 本文の Test plan の同じ行も修正

決定の記録（決定 1〜6）の見出しは変えていない。設計文書は 327 行（上限 500）。

[takemi-ohama]

🤖 cross-review | round 3 | codex | APPROVE

指定コミットの要求仕様・設計と既存実装を照合し、修正を要する指摘はありません。

[takemi-ohama]

🤖 cross-review | round 3 | agy | REQUEST_CHANGES

全体として round 1・round 2 のレビュー指摘が正確に反映され、設計の具体性と堅牢性が大幅に向上しています。
通常実行時における env token の不要なトークン発行・エラー順序の逆転防止（処理順序）と、対象コンテナ解決時の dev サービス絞り込み条件について、2点インラインで指摘しました。ご確認・反映をご検討ください。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 3)

対応件数: critical=0 / major=1 / minor=1 (合計 2 件)
deferred: 0 件 / rejected: 0 件
commit: b11e92b
CI: PENDING（push 直後。前コミット 8b47379 は 5 チェックすべて success）

詳細

• 設計 env token の処理の順（major / architecture） — ログイン（issue_token()）をプロジェクト・接続先・対象の解決の後へ移し、--print だけが backend の判定の後すぐログインする形に。届け先が無いときにサーバへ token を発行しない理由（使われない token が 1 時間残る、到達できない端末で本当の誤りが読めない）を本文に記載。状況表を処理の順に並べ直し、構成要素表・シーケンス図・テスト設計 6 を揃えた
• 設計 対象の解決の絞り込み（minor / edge-case） — docker ps --filter label=com.docker.compose.project=<project> に加え com.docker.compose.service が <dev>-<n> のものだけを残す仕様を明記（根拠: .docker-compose.scale.yml が dev の各インスタンスを {dev}-{i} で定義する）。DB・snapshot が届け先に入らないことと、up 側は resolve_container_name で組むことを併記。テスト設計 6 に固定対象を追加

決定の記録（決定 1〜6）の見出しは変えていない。設計文書は 346 行（上限 500）。

[takemi-ohama]

🤖 cross-review | round 4 | kiro | REQUEST_CHANGES

要求仕様（PLAN54_bao-in-container.md:73）が対象範囲に含める docs/specifications/secret-backend.md への確定仕様追記が、設計の構成要素表・テスト設計表のどちらにも成果物として現れていない。設計を成果物リストとして辿ると実装で抜けるため、構成要素表に spec 追記の行を足すか、要求仕様の対象範囲から外す旨を明記してほしい（インライン参照）。

[takemi-ohama]

🤖 cross-review | round 4 | agy | APPROVE

設計・要求仕様ともに既存コードベース（compose 生成、docker context 解決、コンテナ名の解決、cli サブコマンド定義）と整合しており、round 1〜3 のレビュー指摘（トークン書き込みの原子的実行、env token の処理順序と dev サービス絞り込み）も適切に反映されています。修正が必要なアクションはありません。

[takemi-ohama]

🔧 /ndf:fix サマリ (round 4)

対応件数: critical=0 / major=1 / minor=0 (合計 1 件)
deferred: 0 件 / rejected: 0 件
commit: 9941a20
CI: PENDING（push 直後。前コミット b11e92b は 5 チェックすべて success）

詳細

• 設計 構成要素の表（major / 整合性） — docs/specifications/secret-backend.md（変える。実装 PR のマージ後に plan-to-spec で）の行を足し、spec のどの節へ何を足すかを明記。「構成要素」（container_token.py の行と図の 2 本の辺）、「OpenBao との契約」（「token はディスクへ保存しない」の条件の改めと BAO_ADDR / ~/.vault-token の入出力契約。PLAN55 も同じ節へ足す予定なので節は新設しない）、「devbase env token」の節、「セキュリティ」「運用」「テスト観点」。テスト設計にも受け入れ条件を持たない成果物として plan-to-spec 時の照合を記した

決定の記録（決定 1〜6）の見出しは変えていない。設計文書は 349 行（上限 500）。

[takemi-ohama]

🤖 cross-review | round 5 | kiro | COMMENT

設計文書として要求仕様・既存コード（_apply_window_titles / _write_command / _NO_SECRET_INJECTION / SUBCMD_MAP / choose_context / Dockerfile の USER 構成）との整合はよく取れています。1 点、_run_deploy_pipeline の SecretStore 再利用の記述が現状のコードと現在形で食い違う箇所を inline に残しました（実装で加える変更として書き分ける提案）。ブロッカーではありません。

[takemi-ohama]

🤖 cross-review | round 5 | codex | REQUEST_CHANGES

修正指摘1件（minor）。