概要
テナントが持つ BOT アカウントの認証と管理の設計と、判断の理由を記述する。現在の振る舞いと API の定義元はテナントの BOT アカウントの仕様である。
データモデル
users.account_kind は human または bot とし、既存の利用者は既定値 human になる。
BOT は users.bot_tenant_id に所有テナントを一つ持ち、通常の tenant_members を必ず作成する。
既存の project_members、役割、personal_tokens を共有し、認可を二重に実装しない。
BOT のメールは UUID から作る @bots.task.invalid のアドレスとする。
メールの参照が本人向け DTO、OAuth の照合、招待、本文テンプレートに広がっているため、今回の変更では nullable にしない。
人の新規登録ではこのドメインを拒否し、マイグレーションの制約で BOT のアドレスをその UUID に結び付ける。
既存の利用者はアドレスにかかわらず human のまま移行する。
同じ制約で BOT のパスワード、TOTP の有効化、プラットフォーム管理者への昇格を拒む。
メール用途の棚卸し
| 用途 | 経路(呼ぶ順) | BOT の扱い |
|---|---|---|
| 通知、割り当て、コメント、メンション、レビュー | service::notifications、job::notification_email::send_one |
利用者種別で送信待ちを破棄し、SMTP の直前でも専用アドレスを除外 |
| 新規登録と認証メールの再送 | handlers::auth::{register,resend_verification_email}、job::verification_email |
専用ドメインの登録を拒否し、BOT には再送しない。最後に SMTP でも除外 |
| メールの本人確認 | handlers::auth::verify_email |
BOT のトークンを受け付けず、認証済みに変更しない |
| 登録済みアドレスへの案内 | job::already_registered_email、service::already_registered_email_delivery |
SMTP の直前で除外 |
| パスワードの再設定 | handlers::password_reset、job::password_reset_email |
BOT は要求時に送信を予約せず、トークン検証と完了も拒否 |
| システム管理者の再設定と宛先の上書き | handlers::admin_users::password_reset、service::password_reset_delivery |
BOT はメールの予約前に拒否。宛先を人の実アドレスへ変えた場合も拒否 |
| 再設定の本文生成の二系統 | service::{password_reset_delivery,password_reset_email_delivery} |
両方とも共通の SMTP 判定で除外 |
| テナントへの招待と再送 | handlers::tenant_invitations、job::tenant_invitation_email、service::tenant_invitations::send_invitation_email |
BOT のアドレスへの招待を拒否し、古いジョブも SMTP の直前で除外 |
| OAuth 初回登録時の確認 | handlers::oauth::create_oauth_user_and_connection、job::verification_email |
BOT 専用ドメインは人として保存できず、SMTP でも除外 |
| デスクトップ通知 | 端末トークンと通知 API | メール送信ではない。BOT の端末認証は拒否 |
SmtpClient::send_email の除外は実 SMTP と試験用 Capture の分岐より前に置く。
各テンプレートから BOT と人の対照アドレスへ送る統合試験で、BOT の記録が Capture に一件も入らないことを確かめる。
対話用の入口
以下のパスには /v1 を付ける。
| ハンドラー | ルート | 拒否する位置 |
|---|---|---|
auth::login |
POST /auth/login |
BOT 専用アドレスと共通セッション発行処理 |
auth::register |
POST /auth/register |
BOT 専用ドメインを人の登録に使う操作 |
auth::{verify_email,resend_verification_email} |
POST /auth/{verify-email,resend-verification-email} |
利用者種別 |
passkeys::{registration_start,registration_finish} |
POST /auth/passkeys/registration/{start,finish} |
セッションの利用者種別 |
passkeys::{authentication_start,authentication_finish} |
POST /auth/passkeys/authentication/{start,finish} |
開始はアカウント有無を隠す既存挙動を保ち、署名確認後のセッション発行前に BOT を拒否 |
oauth::oauth_start |
GET /auth/oauth/{provider} |
認証済み利用者の種別を確認し BOT を拒否する |
oauth::oauth_callback |
GET /auth/oauth/{provider}/callback |
既存接続の利用者と接続追加先、共通セッション発行処理 |
oauth::set_initial_password |
POST /auth/password |
セッションの利用者種別 |
auth_2fa::{totp_setup,totp_verify_setup} |
POST /auth/2fa/totp/{setup,verify-setup} |
半認証を含むセッションの利用者種別 |
auth_2fa::verify_2fa |
POST /auth/2fa/verify |
半認証セッションの利用者種別 |
password_reset::{password_reset_request,password_reset_verify,password_reset_complete} |
POST /auth/password-reset/{request,verify,complete} |
要求は存在を隠す既存の 200 応答で配信を抑止し、トークン確認と更新では拒否 |
password_reset::password_change |
POST /auth/password/change |
セッションの利用者種別 |
desktop_auth::create_desktop_auth_code |
POST /desktop/auth/codes |
人のセッションを必須にする |
desktop_auth::exchange_desktop_auth_token |
POST /desktop/auth/token |
コードを引いた後の利用者種別 |
tenant_invitations::accept_invitation |
POST /invitations/accept |
人のセッションを必須にする |
auth::{me,update_me}、管理用の extractor |
GET/PATCH /auth/me ほか |
保存済みセッションから利用者を読むたびに BOT を拒否 |
PAT の照合では is_suspended と、束縛が BOT の所属テナント 1 件だけであることを確認する。
BOT に対する Device Token とブラウザーのセッションは、保存済みの値が残っていても利用者の取得時に拒否する。
テナントの 2FA 強制
BOT はテナントの 2FA の強制(require_2fa)の対象から外す。
BOT は TOTP もパスキーも持てず、セッションにも入れないので、強制の下では PAT で業務のエンドポイントを使えなくなるため。
2FA は人の対話のサインインを守る物で、BOT は PAT でしか入らない。
BOT の作成と PAT の発行は 2FA の強制を満たした人の Admin だけができるので、強制の意図は発行の所で保つ。
免除は BOT に限り、2FA を満たさない人の PAT は従来どおり 403 になる。
管理 API
| メソッド | パス | 用途 |
|---|---|---|
| GET / POST | /v1/tenants/{tenant_id}/bots |
一覧と作成 |
| PATCH | /v1/tenants/{tenant_id}/bots/{bot_id} |
停止と再開 |
| GET / POST | /v1/tenants/{tenant_id}/bots/{bot_id}/tokens |
PAT のメタデータ一覧と発行 |
| DELETE | /v1/tenants/{tenant_id}/bots/{bot_id}/tokens/{token_id} |
PAT の取り消し |
管理 API は人のセッションに限定し、tenant_members と同じく ensure_tenant_access を通す。
テナントが 2FA を強制していれば、2FA を満たさない Admin は全ての管理 API で 403(2fa-setup-required)になる。
BOT の役割は Member 相当まで(TenantRole と ProjectRole の allowed_for_bot)に縛る。
BOT の作成、テナントとプロジェクトのメンバーの追加と役割の変更で、BOT に Admin を渡すと 400(bot-role-too-strong)で断る。
誰が頼んでも通らない願いの誤りなので、403 ではなく 400 にした。
役割は tenant_members と project_members に、BOT の種別は users にあり、CHECK 制約は他の表を見られないので、DB の制約では持たない。
Admin の役割にはメンバーを追加し昇格させる力があるため、BOT が Admin になれれば、その PAT から人へ権限を委ねられる。この縛りでその道を塞ぐ。
自動化に Admin の力が要るようになったら、この上限を緩める余地を残す。
BOT は個人用プロジェクト(My Tasks の Inbox)を持たない。個人用プロジェクトでは持ち主が Admin になり、テナントの外の人をゲストとして加えられるため。
個人用プロジェクトを作る、引くエンドポイント(GET /v1/tenants/{tenant_id}/users/me/personal-project)は、BOT には 404 を返し、行を作らない。BOT には無い資源なので、400 ではなく 404 にした。
書き込みと同じトランザクションで管理者の利用者行、テナント行、所属行を共有ロックし、権限確認の直後に降格される競合を防ぐ。
PAT の発行と停止は同じ BOT 行を排他ロックする。
発行時は必須の期限を現在より後、365 日以内に制限する。
画面は端末の時計から期限を作るので、上限には時計の食い違いに備えて 5 分の猶予を足す。
プロジェクト指定は所有テナント内だけに許す。
作成、PAT の発行と取り消し、停止と再開を audit_logs に同じトランザクションで記録する。
既存のテナント全体の PAT 一括失効でも、対象の BOT ごとに鍵の取り消しを記録する。
操作者とテナント、BOT の ID、操作種別、必要な場合は PAT の ID を記録し、平文の鍵やハッシュは載せない。
GET /v1/personal_tokens/me は既存の応答に account_kind を追加する。
既存 CLI は追加フィールドを無視できるため、コマンドや認証方式を変更しない。
利用者の表示
| 表示箇所 | データと部品 |
|---|---|
| タスクの担当者と作成者 | UserSummary.account_kind と UserAvatar |
| 担当者の選択候補 | UserSummary.account_kind と UserSelector の補足の字(BOT アカウント) |
| コメントと返信の投稿者 | CommentUser.account_kind と UserAvatar |
| タスクの操作履歴 | ActivityUser.account_kind と TaskActivityEntry、UserAvatar |
| ダッシュボードの最近の動き | ActivityUser.account_kind と UserAvatar |
| テナントとプロジェクトのメンバー | UserSummary.account_kind と UserAvatar |
| カレンダーの担当者 | UserSummary.account_kind と CalendarTimeline の行データ、UserAvatar |
| BOT 管理の一覧 | BotResponse.account_kind と TenantBotsSection |
| 利用者のプロフィール | UserProfileResponse.account_kind と UserAvatar |
| 自分のプロフィールとアカウントメニュー | BOT はセッションへ入れないため、人の表示だけを扱う |
| メンション本文 | 既存の名前解決と所属判定を共有する。本文の構文は変更しない |
停止とロールバック
BOT 単体の削除 API は設けない。 汎用の利用者管理 API では BOT の権限変更、削除、認証情報の操作を拒否し、テナントの BOT 管理へ集約する。 停止して利用者レコードを残すことで、コメントなどの投稿者を維持する。 テナント全体を削除する場合は、既存の削除処理に従ってそのテナントの BOT も削除する。 停止時に既存 PAT を取り消すため、再開後も古い鍵は使えない。
マイグレーションの down は、BOT の PAT を取り消し、利用者を停止し、セッション失効時刻を進めてから追加列と制約を取り除く。
旧版へ戻した後も、BOT だった利用者の履歴は停止中の利用者として残る。
再び up した場合、全レコードの種別は human になるため、BOT の所有情報を復元するにはロールバック前のバックアップが必要になる。
