OpenBao backend を、利用者が個人・チームで自分のサーバを立てて使う前提の文書と雛形に揃える #295

何をしたいか

devbase の OpenBao backend を、利用者が個人またはチームで自分の OpenBao サーバを立てて使う前提で使えるようにする。

今の文書と設計は、ある 1 つの組織が運用しているサーバへ接続することを前提に書かれている。OSS として多くの人が使うなら、サーバの用意から devbase の接続までを、利用者が公開の情報だけで再現できる必要がある。

今どうなっているか

main = 2ee7e27（2026-10-06）で確認した。

提案

確かめること

• openbao.url を http://127.0.0.1:8200 にしたとき、devbase up がコンテナへ渡す BAO_ADDR（lib/devbase/commands/container.py:921-932 の _bao_environment）がコンテナの中から届くか。_bao_environment は openbao.url をそのまま BAO_ADDR に入れ、loopback の宛先を書き換えないため、コンテナの中の 127.0.0.1 はコンテナ自身を指す。届かないなら、個人の手元のサーバの形では、コンテナの中の bao が使えない
• 個人の 1 人の利用で、version: 2（グループ別の置き場）と group_aliases が要るか。要らないなら、個人の形の既定をどうするか。アカウントグループの宣言は必須で、default は予約語として弾かれる（アカウントグループの default を廃止し、全プロジェクトでグループの宣言を必須にする #315）。backend を問わず各プロジェクトの env に DEVBASE_ACCOUNT_GROUP が要るため、個人の形で宣言するグループ名（例: personal）を合わせて決める
• AppRole のほかに、個人の形で token による認証を足す価値があるか（足すなら、token の保存先と期限切れの扱い）
• 雛形のポリシーで、今の受け入れ条件（他人のパスは 403、チーム共通への書き込みは権限のある人だけ）が満たされるか。実機の OpenBao（2.6 系）で確かめる

決めること

• devbasex が共通の OpenBao サーバを 1 台運用する案は採らない（2026-09-26 に決定）。 利用者が個人またはチームで自分のサーバを立てる形（セルフホスト）を前提にする。試用のための共通サーバも、この課題では作らない。理由は次の 4 つ
  • 全利用者の機密が 1 か所に集まり、侵害されたときの被害が全利用者に及ぶ。その責任を OSS の運営が負う
  • 利用者と端末の資格情報の発行・失効、濫用への対応、可用性、費用が続く。ツールの開発ではなくサービスの運営になる
  • 機密を自前で持ちたいから OpenBao を選ぶ利用者が多い。手順と雛形があれば、同じ構成を誰でも再現できる
  • 多数の他人で 1 台を共有すると、ポリシーの誤りがそのまま他人の機密の漏れになる
• ポリシーの雛形とサーバを試す構成をどこに置くか（docs/ か、配布物に含めるか）
• 個人・チーム・既存のサーバの 3 つの形を、1 つの文書にまとめるか分けるか
• devbase env backend use openbao に、個人の形の初期設定を助ける機能（例: ポリシーの雛形を書き出す副命令）を足すか、文書だけにするか

完了条件

• 管理者のいない個人が、公開の文書と雛形だけで OpenBao サーバを立て、devbase env backend use openbao で接続し、env set / env get / devbase up の機密の読み込みまで通せる
• チームで 1 台立てたとき、本人以外の個人の置き場が 403 になり、チーム共通への書き込みが権限のある人だけに限られることを、雛形のポリシーで確かめてある
• 利用者向けの文書と確定仕様が、特定の組織のサーバや運用の決まりを前提にしていない

関連

• feat: devbase list の TUI で env を編集できるようにし、グループ・個人の区別と OpenBao の設定もそこで扱う #273（閉じた）— devbase list の TUI の「OpenBao の接続設定」（lib/devbase/tui/actions_env_openbao.py）が入った。この画面は token を入力させず保存もしない。個人の形で token の認証を足すなら、この画面と揃える
• 作成者の所属組織・顧客・個人に固有の名前が文書・コード・テストに残っていて、OSS として読む人に意味が通らない #294（閉じた）— 固有の情報の除去。組織のグループ名の置き換えは 作成者の所属組織・顧客・個人に固有の名前が文書・コード・テストに残っていて、OSS として読む人に意味が通らない #294、サーバの前提の書き直しはこの課題
• アカウントグループの default を廃止し、全プロジェクトでグループの宣言を必須にする #315（閉じた）— 前提 10 の team/personal/… のポリシーを、公開の雛形としてこの課題が示す。アカウントグループの default を廃止し、全プロジェクトでグループの宣言を必須にする #315 の完了はこの課題を待たない

由来

利用者からの依頼（2026-09-26）。「OSS として多くの人が利用する場合は、利用者が個人・チームでそれぞれのサーバを立てる前提での運用が必要」。

依頼（原文）

OSS として多くの人が利用する場合は、利用者が個人・チームでそれぞれのサーバを立てる前提での運用が必要

（書き手: 利用者、日付: 2026-09-26。本文の「由来」の節が引いた依頼の文）

devbasex は共通の OpenBao サーバを運用しない。利用者が個人またはチームで自分のサーバを立てる形（セルフホスト）を前提にする
試用のための共通サーバも、この課題では作らない。要るなら別の課題で扱う

（書き手: 起票者が利用者の決定を記録したコメント、日付: 2026-09-26。決定の記録として、利用者が決めた条件に扱う）

個人の形も version: 2（グループ別の置き場）にそろえ、宣言するアカウントグループの名前は personal にする。形が 1 つで済み、後からチームの形へ移りやすい
認証は AppRole だけにする。token による認証は足さない（保存先と期限切れの扱いを持ち込まない）

（書き手: 起票者が利用者の決定を記録したコメント「決定（2026-10-11 利用者）」、日付: 2026-10-11。同上）

上の 3 つのほかの本文（何をしたいか・今どうなっているか・提案・確かめること・決めること・完了条件）は起票者が書いた。
利用者の指示の原文としては扱わず、原文に無い条件は次の「起票者の推定」に写す。

起票者の推定

題・本文のうち、利用者の指示の原文に無く起票者が推して足した条件。承認ゲート 1 で利用者が確かめるまで、利用者の決定として扱わない。

目的

• 組織の管理者がいない個人や小さなチームが、公開されている文書と雛形だけで自分の OpenBao サーバを立て、
  devbase の OpenBao backend で機密を扱えるようにする
• 利用者向けの文書と確定仕様から、特定の組織が運用するサーバと運用の決まりを前提にした記述を無くす

前提

• 前提 1: devbasex は共通の OpenBao サーバを運用せず、試用のための共通サーバも作らない（2026-09-26 の決定）
• 前提 2: 認証は今の AppRole（利用者ごとの role_id・端末ごとの secret_id）だけで、token による認証は足さない（2026-10-11 の決定）
• 前提 3: 個人の形も version: 2（openbao.layout: group）を使い、プロジェクトが宣言するアカウントグループは personal とする（2026-10-11 の決定）。個人の形で group_aliases は使わない
• 前提 4: 対象の OpenBao は base イメージの bao と同じ 2.6 系（containers/base/Dockerfile の ARG BAO_VERSION=2.6.2）とする。ほかの版での動作は確かめない
• 前提 5: devbase がサーバへ送る要求（4 経路のパス・KV v2 の API・AppRole のログイン）は変えない。サーバの側の雛形と文書を、今の devbase の要求に合わせる
• 前提 6: bao server -dev は機密を記憶にだけ置き、止めると消える。試用の構成は本物の機密を置く場所としては案内しない
• 前提 7: 実機の確認は、利用者の実際の環境の devbase up（P3）を使わず、作業用のプロジェクトと試用のサーバで行う。利用者の環境での確かめはリリース後テストで利用者が行う

対象範囲

含む:

• 利用者向けの文書（docs/user/env-backend.md と、要れば新しい文書）の、サーバの用意から接続までの手順
• OpenBao のポリシーの雛形（HCL）と、試用の構成（起動の手順か compose のファイル）をリポジトリに置くこと
• 確定仕様（docs/specifications/secret-backend.md）の、サーバの前提の書き直し（393・922・926-929・1418-1420・1652 行の付近）
• コンテナの中の bao が、個人の形の構成で使えるかの確認と、その結果に合わせた文書（届かせるためにコードを変えるかは未決 4）
• 用語集への語の追加

含まない:

• devbasex が運用する共通の OpenBao サーバ、試用のための共通サーバ（前提 1）
• token による認証（前提 2）
• サーバの冗長化・バックアップ・監査ログ・TLS の証明書の発行など、サーバの本番の運用の手順（公式の文書へのリンクにとどめる）
• 組織のグループ名などの固有の語の置き換え（作成者の所属組織・顧客・個人に固有の名前が文書・コード・テストに残っていて、OSS として読む人に意味が通らない #294 で済んでいる）
• base イメージの bao の版の変更（P1）
• devbase がサーバへ送る要求の変更（前提 5）

ドメインイベント

用語

受け入れ条件

文書と雛形:

• 1. 利用者向けの文書が、利用の形の 3 つ（個人・チーム・既存のサーバ）を見出しで分け、それぞれで利用者が何を用意するかを示している
• 2. 個人の形とチームの形の文書が、KV v2 のマウント（既定 devbase）・AppRole の有効化・ポリシーの書き込み・entity と alias の作成・利用者ごとのロールの作成・端末ごとの secret_id の発行を、bao のコマンドで順に示している
• 3. チームの形の文書が、利用者と端末を足す手順と、端末 1 台の secret_id を失効させる手順を bao のコマンドで示している
• 4. ポリシーの雛形がリポジトリに HCL のファイルとして置かれ、version: 1 と version: 2 の両方がある。どの雛形も OpenBao 2.6 系の bao policy write で拒まれない
• 5. version: 2 の雛形は、グループの名前を書き換えるだけで team/<group>/… の置き場に使える（例として personal を示す）。雛形の中に特定の組織の名前が無い
• 6. 試用の構成が、個人が手元の 1 台で OpenBao を起動し、受け入れ条件 2 の手順を打ち、devbase env backend use openbao で接続するまでを示している。起動を確かめるコマンドと、止めると機密が消えること（前提 6）を書いている
• 7. 試用の構成の文書が片付けの手順を持ち、サーバを止めることと、devbase の backend を元へ戻すこと（secrets/backend.yml と secrets/bootstrap.env.age の扱い）を含んでいる。手順の後に devbase env backend status が OpenBao を指していない
• 8. 個人の形の文書が、コンテナの中の bao を使えるかと、使うときの openbao.url の書き方を明記している。使えると書いた構成では、dev コンテナの中の bao kv get が本人の個人共通の置き場を読める
• 9. docs/user/env-backend.md から「サーバの構築と運用は devbase の範囲外です。管理者から次の値を受け取ってください」の前提が消え、既存のサーバの形でだけ「管理者から受け取る」と書かれている
• 10. 利用者向けの文書と確定仕様が、利用者の識別子（設定の user）を「サーバの entity 名と同じ識別子」と説明し、「社内メールアドレス」の語が docs/user/ と docs/specifications/secret-backend.md に無い
• 11. docs/specifications/secret-backend.md に「運用側のリポジトリ」の語が無く、関連リンクから運用側のリポジトリへの参照が消えている
• 12. docs/specifications/secret-backend.md が、devbase がサーバに求める条件（KV v2 のマウント・4 経路のパス・AppRole のログイン・本人のパスの読み書き・チームのパスの読み取り・チーム共通への書き込みは権限のある人だけ・他人のパスと users/ 直下の一覧の拒否・version: 2 のグループ単位の権限）を書き、ポリシーの雛形の置き場を示している

実機（OpenBao 2.6 系）:

• 13. 前提: 管理者のいない端末。操作: 公開の文書と雛形だけを見て、試用の構成でサーバを立て、devbase env backend use openbao で接続し、DEVBASE_ACCOUNT_GROUP=personal を宣言した作業用のプロジェクトで env set → env get → devbase up を打つ。結果: env get が書いた値を返し、up したコンテナの環境変数にその値がある
• 14. 前提: version: 2 の雛形を書き込んだサーバに、利用者 2 人（member01・member02）がいて、チーム共通への書き込みは member01 にだけ許している。結果: member02 の資格で users/member01/… の読み取りが 403、member02 のチーム共通への書き込みが 403、member01 のチーム共通への書き込みと両者のチーム共通の読み取りが通る。version: 1 の雛形でも、他人の個人の置き場の 403 とチーム共通への書き込みの制限が同じく効く
• 15. 前提: 受け入れ条件 14 のサーバ。操作: member02 の端末の secret_id を失効させる。結果: その端末の devbase env backend test がログインの失敗で止まり、member02 の別の端末の secret_id ではログインが通る

退行しないこと:

• 16. 既存のサーバの形の利用者は、secrets/backend.yml と secrets/bootstrap.env.age を変えずに、これまでと同じコマンドで機密を読み書きできる（env-backend.md の接続の手順のコマンドと引数が変わらない）
• 17. env -u DEVBASE_ROOT uv run --locked pytest tests/ -q が通る
• 18. python3 .github/scripts/proper_term_check.py が「語の一覧が無いため飛ばした」と出さずに通る（固有の語の一覧のある端末で打つ）

非機能の条件

影響

検証手段

前提とする取り決め

境界

未決

進行

モード: —

• 要求と受け入れ条件 — 2026-10-12 22:27
• 作業場所の用意 — 2026-10-12 22:54
• 設計 — 2026-10-12 22:31
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-12 22:53
• 実装 — 2026-10-12 23:16
• 構造改善 — 2026-10-12 23:51
• 実装レビュー — 2026-10-13 00:09
• 完了判定 — 2026-10-12 23:32
• Pull Request — 2026-10-12 23:35
• 確定仕様化 — 2026-10-13 00:50
• 後片付け — 2026-10-13 01:00
• 配布 — 2026-10-13 01:00
• 体裁レビュー
• リリース後テスト — 2026-10-13 01:03
• 振り返り — 2026-10-13 01:03
• 棚卸し — 2026-10-13 01:20

振り返り: #472 (comment)