Linear migration metadata¶

• Linear issue: TAK-240
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-240/kandkホスティング連携モードを追加しepaa単体利用と切り替えられるようにする
• Linear status: Backlog
• Linear team: Takayuki Komoda
• Linear project: EPAA Core
• Linear assignee: Takayuki Komoda
• Linear labels: Feature
• Linear created: 2026-08-24T08:27:43.394Z
• Linear updated: 2026-09-26T00:06:03.721Z
• Linear archived:

---

Original description¶

背景¶

K&Kのホスティングサービスと連携したサービス展開を想定し、EPAAを単体で利用する従来モードに加えて、K&K側の環境・設定発行に追従する利用モードを追加したい。

現状のEPAA単体利用は維持しつつ、K&K連携時はEPAA側で不要なプロジェクト管理や環境別設定入力を省き、導入・運用の手間を減らす。

要求¶

• EPAA単体利用モードを維持する。
• K&Kホスティングサービス連携モードを追加する。
• K&K連携モードでは、EPAA側で複数プロジェクトを作成・管理しなくてよい構成にする。
• K&K連携モードでは、dev / stg / 本番の接続先・環境設定をEPAA側で一つずつ登録させない。
• dev / stg / 本番の設定はK&K側で発行される前提とし、EPAAはその発行情報を参照または取り込んで動作する。
• K&K連携モードとEPAA単体モードの違いが、管理画面・生成・リリース・検証手順で混同されないようにする。

非目標¶

• EPAA単体利用モードを廃止しない。
• K&K側のホスティングサービスそのものの実装はこのIssueの直接対象外とする。
• dev / stg / 本番をEPAA側で個別に手入力・個別管理する前提にはしない。

受入条件¶

• 管理者がEPAA単体モードとK&K連携モードのどちらで運用するか判別できる。
• K&K連携モードでは、複数プロジェクト作成を前提にしない操作導線になっている。
• K&K連携モードでは、dev / stg / 本番ごとの設定値をEPAA側で個別登録しなくても環境情報を扱える。
• 既存のEPAA単体利用・ローカル検証・dev.epaa.jp検証の前提が壊れていない。
• 設定が生成挙動やリリース挙動に影響する場合、YAML直編集だけでなくEPAA GUIから作成・編集・削除できる管理経路が定義されている。

影響範囲候補¶

• Core GUI: モード選択、プロジェクト/環境設定画面、表示文言、入力制御
• Backend/API: K&K連携設定の取得・保存・検証、モード判定、リリース/環境情報参照
• DB: 連携モードやK&K発行情報を保持する場合のテーブル/リリースSQL
• OpenAPI: fixed APIを追加・変更する場合は先に契約を定義
• Generator/Runtime: 環境別生成・リリース手順に影響する場合は境界を明確化
• Docs: EPAA単体利用とK&K連携利用の運用手順を分けて記載
• Test: 5002検証、設定レポート、API検証マトリクス、必要に応じてブラウザ証跡

注意事項¶

• 実装前に要件定義・設計レビューを行い、単体モード互換性とK&K連携モードの責務境界を確定する。
• K&K側が発行する設定の形式、取得方法、認証方式、更新タイミングは未確定事項として設計で整理する。
• 子Issueは設計後に FE / BE / DB / Test / Docs へ分割するか判断する。
• NotionのEPAA開発管理へ背景・決定事項を残すかは別途確認する。

---

実装前API契約・責務境界（2026-09-02整理）¶

確定方針¶

• EPAA Coreは利用者PC上のデスクトップ／ローカルWebとして動作する。
• CoreはOAuth 2.0/OIDCのPublic Clientとし、Authorization Code + PKCE（S256）を使用する。Client Secretは配布・保持しない。
• Redirect URIは http://127.0.0.1:{ephemeral-port}/oauth/callback のループバック方式とする。Coreは認可開始時だけ待受し、完了またはタイムアウト後に閉じる。
• state、OIDC nonce、PKCE verifierを毎回生成し、認可レスポンスで厳密検証する。組み込みWebViewは使わずOS既定ブラウザを使う。
• 初期管理者パスワードはAPIで受け渡さない。bootstrap は単回利用・短寿命の初回設定URLを返す。
• K&K側がID/PW、MFA、端末承認、契約・支払い状態、接続許可を所有する。
• Core側がPKCE、一時トークン、SSH秘密鍵、ローカル設定、セットアップ実行を所有する。
• K&Kへ送るのはSSH公開鍵のみ。CoreはK&KのID/PW、初期管理者パスワード、SSH秘密鍵を受信・送信・ログ保存しない。
• K&K API未完成中は、同一OpenAPI契約から生成または実装したスタブでCore開発を先行する。

API契約のたたき台¶

OAuth/OIDC¶

• GET /oauth/authorize
  • 必須: response_type=code, client_id, loopback redirect_uri, scope, state, nonce, code_challenge, code_challenge_method=S256
  • K&K側でMFA・端末承認・有効契約を確認する。
• POST /oauth/token
  • application/x-www-form-urlencoded
  • 必須: grant_type=authorization_code, code, client_id, redirect_uri, code_verifier
  • Public ClientのためClient Secretは禁止。
  • Access Tokenは短命、AudienceをK&K Core APIに限定する。Refresh Tokenを採用する場合はローテーション必須、OS資格情報ストアへ保存する。
• 推奨scope: openid core.bootstrap core.deploy-key.write core.setup-result.write

GET /api/v1/core/bootstrap¶

• 有効契約・端末承認済みのTokenのみ許可。
• 応答候補: contractId（opaque ID）、configRevision、environments[]（dev/stg/prod）、FQDN、SSH接続先、固定サーバ設定、DB接続設定、adminSetupUrl、adminSetupExpiresAt。
• adminSetupUrl はHTTPS、単回利用、短寿命とし、使用後・期限切れ後はK&K側で再発行する。
• テナントID、顧客名、組織名、利用可能機能、平文パスワードは返さない。
• Cache-Control: no-store。ETag/configRevisionにより同一スナップショットを識別する。
• URLや接続設定に資格情報を埋め込まない。DB秘密情報が必要なら別途短命Secret取得方式を契約レビューで決定する。

POST /api/v1/core/deploy-keys¶

• 必須Header: Idempotency-Key、Bearer Token。
• 要求候補: publicKey、fingerprint、environments[]、requestedTtlSeconds。
• 応答候補: deployKeyId、fingerprint、allowedEnvironments[]、validFrom、expiresAt、接続制約。
• 公開鍵形式・アルゴリズム・最小鍵長をallowlist化する。秘密鍵や任意のauthorized_keys optionは受理しない。
• 同じIdempotency-Key＋同じpayloadは同じ結果を返し、異なるpayloadは409。

POST /api/v1/core/setup-results¶

• 必須Header: Idempotency-Key、Bearer Token。
• 要求候補: setupAttemptId、configRevision、status（succeeded/failed）、startedAt、finishedAt、steps[]、安全化済みerror。
• setupAttemptIdを業務冪等キーとし、再送で二重処理しない。
• 同一Attemptの同一結果は成功扱い、矛盾する終端結果は409。
• ログ本文、Token、パスワード、秘密鍵、接続文字列は送信しない。

共通エラー契約¶

• application/problem+json（RFC 9457）に統一する。
• 必須候補: type, title, status, code, detail, traceId, retryable。
• 主なHTTP status:
  • 400: schema/parameter不正
  • 401: Token不正・期限切れ
  • 403: scope不足、契約・支払い・端末承認・接続許可NG
  • 404: 対象契約・設定なし（他契約の存在は秘匿）
  • 409: 冪等キー競合、revision競合、終端状態競合
  • 422: 公開鍵や設定内容の意味的エラー
  • 429: rate limit（Retry-After）
  • 500/502/503/504: K&K側障害・依存先障害
• Coreは retryable=true または429/502/503/504のみ指数バックオフ＋jitterで再試行する。401/403/409/422は自動再試行しない。

冪等性・再実行¶

• bootstrap はGETとして副作用を持たせず、同一configRevisionを再取得可能にする。ワンタイムURL再発行は別操作として扱う。
• deploy-keys と setup-results はUUIDのIdempotency-Keyを必須とし、K&K側で最低24時間保持する。
• CoreはIdempotency-Key、setupAttemptId、deployKeyId、configRevisionをローカル永続化し、プロセス再起動後も同じ処理を再開できるようにする。
• タイムアウトは失敗確定とみなさず、同じキーで再送する。

K&K側と実装前に合意が必要な残項目¶

1. Issuer、Discovery/JWKS URL、client_id、scope、Token署名アルゴリズム、Access/Refresh Token TTL。
2. 可変loopback portのRedirect URI登録方式と認可コード有効期限。
3. bootstrap の各環境schema、必須/nullable、DB秘密情報の扱い、configRevision更新規則。
4. 初回設定URLのTTL、再発行API、URLを開く主体と完了確認方法。
5. SSH公開鍵アルゴリズム、許可先、接続元制限、TTL上限、失効・再発行API。
6. setup step/error code一覧、結果の受付後処理、結果照会の要否。
7. Idempotency-Key保持期間、rate limit、timeout/SLA、監査ログ保持期間。
8. 開発・検証・本番のBase URL、証明書、疎通元、K&K側スタブ／検証環境の提供方法。

Definition of Ready¶

• OpenAPI 3.1で上記endpoint、schema、security scheme、Problem Details、exampleを合意済み。
• K&K/Core双方の責務、秘密情報、ログ禁止項目、Token/SSH鍵ライフサイクルをレビュー済み。
• 正常系、Token期限切れ、契約NG、revision変更、timeout後再送、冪等競合、部分失敗のcontract test例が確定済み。
• Coreスタブが合意OpenAPIに追従し、K&K実装なしでも正常系・主要異常系を再現可能。

Linear comments¶

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-08-25T15:36:39.096Z)¶

Core対応メモ: K&K連携API前提の実装方針¶

K&K側の開発は先方担当とし、EPAA Coreは以下のK&K APIが存在する前提で連携モードを実装する。

前提¶

• EPAA単体利用モードは維持する。
• K&K連携モードでは、ユーザーはCore上でK&Kログインを開始する。
• CoreはK&KアカウントのID/パスワードを直接扱わない。
• K&K側でID/PW、MFA、契約状態、支払い状態、端末承認を確認する。
• Coreは短命トークン取得後に初期設定をAPIで取得する。
• テナントID、顧客名、組織名、利用可能機能はCoreの初期設定には含めない。
• K&K連携モードはシングルテナント前提。

想定フロー¶

1. Coreで「K&Kでログイン」を選択する。
2. CoreがK&Kのログイン画面をブラウザで開く。
3. K&K側でID/PW + MFA + 端末承認を行う。
4. Coreが認可コードを受け取り、トークンを取得する。
5. CoreがK&K APIから契約・FQDN・固定サーバ設定・初期管理者情報を取得する。
6. CoreがローカルでSSH鍵ペアを生成する。
7. Coreが公開鍵だけをK&K APIへ登録する。
8. K&K側が期限付きでSSH/SCP接続を許可する。
9. Coreが初期配置を実行する。
10. Coreがセットアップ結果をK&K APIへ通知する。

K&K API契約案¶

• GET /oauth/authorize: ログイン開始。OAuth2/OIDC Authorization Code + PKCE、MFA、端末承認を必須にする。
• POST /oauth/token: 認可コードを短命アクセストークンへ交換する。
• GET /api/v1/core/bootstrap: 有効契約の初期設定を取得する。
• POST /api/v1/core/deploy-keys: Coreが生成したSSH公開鍵を登録する。
• POST /api/v1/core/setup-results: 初期セットアップの成功・失敗を通知する。

Core側の主な改修候補¶

• 起動時または初期設定画面で「単体利用 / K&K連携利用」を選択できるようにする。
• K&Kログイン開始、PKCE、認可コード受信、トークン取得を実装する。
• トークンを端末登録と紐付けて安全に保存・失効できるようにする。
• bootstrap レスポンスからFQDN、サーバ固定設定、DB設定、初期管理者情報を取り込み、既存の初期配置設定へ反映する。
• 初期管理者パスワードは受信後すぐハッシュ化し、平文を保存・ログ出力しない。
• SSH秘密鍵はCore側で生成・保管し、K&Kへ送らない。
• SSH公開鍵登録後、既存のSSH/SCP初期配置処理へ接続する。
• セットアップ成功・失敗をK&Kへ通知し、再実行時の冪等性を確保する。

注意事項¶

• K&K側APIが未実装の間は、Core側にK&K APIクライアントのインターフェースとスタブ実装を用意して進める。
• API契約は実装前にOpenAPIまたは同等の仕様として固定する。
• 認証・端末承認・SSH鍵登録はセキュリティ影響が大きいため、FE/BE/API契約レビューとテスト子タスクの分割を検討する。