NDF Factory: Cognito の認証（Google・GitHub）とプランごとの利用量 #2170

移した先: https://github.com/volareinc/nd-factory/issues/26（Factory の開発は移した先で続ける。手順は #2646）

親: #2168（Neural Development Factory）。前提: #2169（v10.25.0 で完了）。

形と契約は #2169 の確定仕様 docs/specifications/ndf-factory-service-boundary.md の「サービス全体の契約（子課題が実装する）」にある。この課題は集約「アカウント」（根: アカウント、エンティティ: 席、値オブジェクト: プラン・使える量・実行の形態）の持ち主である。

依頼（原文）

• Cognitoによる認証(Google, Githubの認証に対応)
  • Claude.aiと類似の認証・課金モデル(Free, 個人PRo, 個人Max, Team(standard/premium sear) etc)

（書き手: 利用者、日付: 2026-10-30。#2168 の構想を伝えた会話の原文のうち、この課題が受け持つ 2 行。全文は #2169 の「依頼（原文）」にある）

親＋機能別の子課題（#2168 を親に子課題 6 本。最初のスプリントは置き場・ライセンスの切り離し・全体設計）

（書き手: 利用者、日付: 2026-10-30。分け方の問いへの回答）

factory/ の TypeScript のパッケージの管理の道具（npm・pnpm）を決める課題を #2171 から #2170 へ移す。最初に TypeScript のコード（factory/web/・factory/api/）を置くのは #2170 であり、道具はその時点で決まっている必要がある。

（書き手: 起票者、日付: 2026-10-30。PR #2185 #2185 の本文が「2026-10-30 の利用者の決定」として記録した文。利用者の原文は確かめられないため、利用者の文としては扱わず、決定の中身（道具を決める課題を #2170 が持つ）だけを利用者の決定として読む）

ランナーが Claude を呼ぶ方法を、アカウントごとに ① local 手元のランナー・② byok キーの持ち込み・③ managed サービスの Bedrock の 3 つから選ぶ。Free は ① と ② だけを選べる。同時のスプリントの数の上限は全形態に掛かり、月の token の上限は ③ だけに掛かる。

（書き手: 起票者、日付: 2026-10-30。PR #2190 #2190 の確定仕様 docs/specifications/ndf-factory-service-boundary.md の「実行の形態」が「2026-10-30 の利用者の決定」として記録した内容の要約。claude.ai のログインをサービスが預かる形は Anthropic の規約が認めないため。この課題が受け持つのは形態の値と選べる条件だけで、ランナーとキーの保存は #2186・#2189、課金は #2174 が持つ）

起票者の推定

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

目的

• Google か GitHub のアカウントで Neural Development Factory にログインでき、ログインした人がどのアカウント（個人かチーム）として操作しているかを、ほかの子課題が token 1 つから確かめられる状態にする
• プランと席ごとに使える量を 1 か所で決め、実行の制御（NDF Factory: スプリントの実行の制御とランナー #2186）と課金（NDF Factory: サブスクリプションと Bedrock の token 課金 #2174）が同じ値を問い合わせて使える状態にする
• factory/ に TypeScript のパッケージの管理の道具を決め、後続の子課題（NDF Factory: contracts と進捗の受け口 #2171・NDF Factory: スプリントの一覧（フェーズ）と詳細（工程・PR・CI・承認ゲート） #2172〜NDF Factory: サブスクリプションと Bedrock の token 課金 #2174・NDF Factory: スプリントの実行の制御とランナー #2186）が同じ形で factory/web/・factory/api/ にコードを足せる状態にする

前提

• 前提 1: Cognito の利用者プール・アプリのクライアント・外部の IdP（Google・GitHub）の登録・ドメインはインフラであり、private リポジトリが作る。この課題はその定義を書かず、受け取る変数の名前を factory/.env.example に足すだけにする（確定仕様の「データ・設定」。値は書かない、I6）
• 前提 2: GitHub のログインを Cognito へつなぐ形（Cognito の OIDC の IdP として直に登録できるか、OIDC の仲立ちのプログラムが要るか）は設計で確かめる。仲立ちが要り、それがインフラでなくサービスのコードなら factory/api/ に置く。仲立ちの秘密（GitHub の OAuth の client secret）は Secrets Manager の ARN（*_SECRET_ARN）だけで受ける
• 前提 3: 1 人の人が Google と GitHub の両方でログインしたとき、2 つは別の利用者として扱い、自動で 1 つにまとめない（メールアドレスの一致でまとめると、片方の IdP でメールを偽れたときに他人のアカウントへ入れるため）。まとめる機能はこの課題に含めない
• 前提 4: アカウントは「個人」か「チーム」のどちらか。初めてログインした利用者には、その人だけの個人のアカウントがプラン Free で 1 つ作られる。チームのアカウントは席を持ち、席はそれぞれ 1 人の利用者と種類（standard / premium）を持つ。個人のアカウントは席を持たない（使える量はプランから決まる）
• 前提 5: チームへ人を入れるのは、チームの持ち主（チームを作った利用者）が、既に 1 度ログインした利用者を指して席を足す操作だけにする。招待のメールの送信はこの課題に含めない
• 前提 6: プランごと・席の種類ごとの使える量の値（同時のスプリントの数・月の token の上限）は、コードの分岐でなく 1 つの表（設定かデータ）で持つ。初めの値は設計で案を出し、ゲート 1 で利用者が決める。値を変えるのは表の 1 か所だけで済む
• 前提 7: 使える量の判定に要る「今の値」（動いているスプリントの実行の数・その月に使った token の数）は、この課題が持たない（スプリントの実行は NDF Factory: スプリントの実行の制御とランナー #2186、使用量の台帳は NDF Factory: サブスクリプションと Bedrock の token 課金 #2174 の集約）。判定は呼び出す側が今の値を渡し、この課題は上限と照らした結果を返す。これで確定仕様の「使う契約は無い」を保つ
• 前提 8: プランを Free 以外へ変える経路（決済の後に誰が何を呼ぶか）は NDF Factory: サブスクリプションと Bedrock の token 課金 #2174 が決める。この課題は、アカウントのプランを書き換える操作を API の内側の関数として持つが、利用者が画面から自分のプランを変える経路は持たない
• 前提 9: 月の境目は UTC の暦月で数える（使用量の事象の at が UTC のため、確定仕様の「進捗の正本」）
• 前提 10: 実行の形態（local / byok / managed）はアカウントの値で、この課題は値と選べる条件だけを持つ。形態ごとのランナー・持ち込んだキーの保存・実行は NDF Factory: スプリントの実行の制御とランナー #2186・NDF Factory: 手元のマシン（利用者の環境で、利用者の claude ログインで実行する） #2189、managed の token の課金は NDF Factory: サブスクリプションと Bedrock の token 課金 #2174 が持つ（確定仕様の「実行の形態」）

対象範囲

含む:

• 画面（factory/web/）: Google か GitHub でログイン・ログアウトする画面と、自分のアカウント（プラン・使える量・チームなら席）を見る画面
• API（factory/api/）: Cognito の token の検証と account_id の解決、アカウント・席・プラン・実行の形態の読み書き、使える量の問い合わせと判定
• チームのアカウントの作成と、席の追加・種類の変更・削除（チームの持ち主だけ）
• factory/ の TypeScript のパッケージの管理の道具の決定と、factory/web/・factory/api/ の雛形（依存の宣言・ロックファイル・型検査・テストのコマンド）
• factory/web/・factory/api/ のテストと型検査を Pull Request で走らせる CI のジョブ
• factory/.env.example への変数の名前の追加と、用語集への語の追加

含まない:

• Cognito の利用者プールなどインフラの定義（private リポジトリ側。前提 1）
• 決済・料金・請求の画面と、プランを有料へ変える経路（NDF Factory: サブスクリプションと Bedrock の token 課金 #2174。前提 8）
• 使用量の台帳と、その月に使った token の集計（NDF Factory: サブスクリプションと Bedrock の token 課金 #2174。前提 7）
• スプリントの開始を断る処理そのもの（NDF Factory: スプリントの実行の制御とランナー #2186。この課題は判定を返す）
• 実行の形態ごとのランナー・持ち込んだキーの保存・Claude の呼び出し（NDF Factory: スプリントの実行の制御とランナー #2186・NDF Factory: 手元のマシン（利用者の環境で、利用者の claude ログインで実行する） #2189。前提 10）
• 2 つの IdP の利用者を 1 つにまとめる機能（前提 3）・招待のメール（前提 5）
• 確定仕様の契約の形の変更。変えるなら設計 Pull Request で確定仕様を先に直す（確定仕様の「サービス全体の契約」の冒頭）

提供する契約

ドメインイベント

用語

受け入れ条件

ログイン:

• 1. ログインの画面に Google と GitHub の 2 つのログインの操作があり、どちらでも Cognito を経てログインでき、ログイン後の画面に自分のアカウントのプランが出る
• 2. IdP の画面で利用者が取り消したか IdP が拒んだとき、ログインの画面へ戻り、ログインできなかったことが出る。token は保存されない
• 3. ログアウトすると、画面が保存した token が消え、API を呼ぶ画面を開くとログインの画面へ移る

認可の token と account_id:

• 4. API は Cognito の token を署名・発行元・対象のクライアント・期限で検証する。token が無い・署名が違う・期限切れ・別の利用者プールかクライアントのもののどれでも 401 を返し、アカウントの中身を返さない。それぞれを 1 つずつ入れたテストで確かめる
• 5. 検証を通った token から、その利用者が操作しているアカウントの account_id を得る関数が factory/api/ にあり、NDF Factory: contracts と進捗の受け口 #2171・NDF Factory: スプリントの実行の制御とランナー #2186・NDF Factory: サブスクリプションと Bedrock の token 課金 #2174 の API が同じ関数を呼んで使える。チームのアカウントを指す要求で、その利用者がチームの席を持たなければ 403 を返す

プランと使える量:

• 6. 使える量の問い合わせに account_id（チームなら席の利用者も）を渡すと、同時に動かせるスプリントの実行の数と月の token の上限が返る。値はプラン（個人のアカウント）か席の種類（チームのアカウント）で決まり、Free・個人 Pro・個人 Max・Team standard・Team premium の 5 つで、表（前提 6）の値と一致する
• 7. 使える量の判定に今の値（動いているスプリントの実行の数・その月の token の数）を渡すと、上限より小さければ許す結果、上限に達していれば断る結果と理由（どの量が・上限がいくつで・今がいくつか）が返る。上限ちょうど・上限より 1 少ない・上限より多いの 3 つの境目をテストで確かめる。月の token を照らすのは実行の形態が managed のときだけである（受け入れ条件 20）
• 8. 画面の自分のアカウントの画面に、使える量の 2 つの上限が出る

チームと席:

• 9. 利用者がチームのアカウントを作ると、作った利用者がチームの持ち主になり、持ち主自身の席が 1 つ（種類は作るときに選ぶ）できる
• 10. チームの持ち主は、既に 1 度ログインした利用者を指して席を足し、席の種類を変え、席を外せる。持ち主でない利用者が同じ操作をすると 403 で、席は変わらない
• 11. 未ログインの利用者を指して席を足す・同じチームに既に席を持つ利用者を足す・持ち主自身の席を外すのどれも断られ、理由が出る。席は変わらない

起きてはいけないこと:

• 12. 同じ利用者が何度ログインしても、個人のアカウントは 1 つだけである（並べて 2 回ログインしても 2 つにならない）
• 13. 利用者 A の token で、A が席を持たないアカウント（他人の個人のアカウント・入っていないチーム）のプラン・使える量・席を読もうとしても書こうとしても 403 で、相手のアカウントの有無と中身が応答に出ない
• 14. このリポジトリに、Cognito の利用者プールなどインフラの定義・秘密・.env の実ファイルが入らない。境界の検査（python3 scripts/check-service-boundary.py）が 0 で終わる

パッケージの管理と検査:

• 15. factory/ の TypeScript のパッケージの管理の道具が 1 つに決まり、factory/web/・factory/api/ に依存の宣言とロックファイルがある。決めた道具と理由が設計文書にあり、後続の子課題が従う規則として factory/README.md に書いてある
• 16. factory/web/・factory/api/ の型検査とテストが、それぞれ 1 つのコマンドで手元と CI の両方で走る。CI のジョブは factory/ を変える Pull Request で走り、落ちれば Pull Request が赤になる
• 17. 既存のテスト（uv run --frozen --project . --all-extras pytest . -q -n 4）・claude plugin validate .・既存の CI の必須チェックが、この変更の前と同じに通る。プラグインの配布物と CLI だけで使う人の振る舞いは変わらない

実行の形態:

• 18. アカウントは実行の形態（local / byok / managed）を 1 つ持ち、アカウントを読む API の応答に出る。NDF Factory: スプリントの実行の制御とランナー #2186・NDF Factory: 手元のマシン（利用者の環境で、利用者の claude ログインで実行する） #2189・NDF Factory: サブスクリプションと Bedrock の token 課金 #2174 は同じ値を account_id から読める
• 19. アカウントの持ち主（個人なら本人、チームならチームの持ち主）は実行の形態を変えられる。持ち主でない利用者が変えようとすると 403 で、形態は変わらない。プランが Free のアカウントで managed を選ぶと断られ、理由（Free では managed を選べない）が出て、形態は変わらない
• 20. 使える量の判定は、実行の形態が managed のときだけ月の token の上限を照らす。local と byok では、その月の token が上限を超えていても月の token を理由に断らない。同時に動かせるスプリントの実行の数は 3 つの形態すべてで照らす

非機能の条件

影響

検証手段

前提とする取り決め

境界

承認の扱い: この変更は共通原則の C2（認証・認可を変える）に当たるため、ゲート 1・2 を MVV の判定で自動に通さず、人が承認ゲートで見る（.ndf/pace.json の fast / auto でも同じ）。承認の工程は足さない。

未決

進行

モード: —

• 要求と受け入れ条件 — 2026-10-30 08:50
• 作業場所の用意 — 2026-10-30 11:37
• 設計 — 2026-10-30 08:54
• 素材の収集と出典の確定
• ドキュメント再構成
• ドキュメントレビュー
• 計画 — 2026-10-30 11:37
• 実装 — 2026-10-30 11:38
• 構造改善 — 2026-10-30 12:29
• 実装レビュー — 2026-10-30 13:14
• 完了判定 — 2026-10-30 12:02
• Pull Request — 2026-10-30 12:14
• 確定仕様化 — 2026-10-30 14:29
• 後片付け — 2026-10-30 14:29
• 配布 — 2026-10-30 13:50
• 体裁レビュー
• リリース後テスト — 2026-10-30 14:28
• 振り返り — 2026-10-30 15:00
• 棚卸し — 2026-10-30 15:00

振り返り: #2170 (comment)

残っていること

実装・配布（ndf v10.26.0、PR https://github.com/devbasex/ai-plugins/pull/2195）は済んでいる。残りは、実環境の Cognito・Google・GitHub・DynamoDB が要る受け入れ条件 1・2・3・4・12 のリリース後テストだけである。インフラ（Cognito の利用者プール・IdP・秘密）は private リポジトリの認証の課題が作り、それができた時点で実際のアカウントでログインして確かめる。