---
title: "テナント BOT の認証と管理"
description: "BOT の認証の拒否、メールの停止、管理 API、役割の上限について、判断の理由を残すページ"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# テナント BOT の認証と管理

## 概要

テナントが持つ BOT アカウントの認証と管理の設計と、判断の理由を記述する。現在の振る舞いと API の定義元は[テナントの BOT アカウント](https://docs.koyori.app/dev/features/tenant-bots)の仕様である。

## データモデル

`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 の所有情報を復元するにはロールバック前のバックアップが必要になる。

Source: https://docs.koyori.app/dev/design/tenant-bots/index.mdx
