---
title: "テナントとプロジェクトの認可"
description: "誰がどのテナント・プロジェクトに入れるかの判定と、継承・明示 ACE・招待の規則"
---

> 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.

# テナントとプロジェクトの認可

## 概要

「誰がどのテナント・プロジェクトに入れるか」の判定を記述する（#568 / #572）。

権限の形は NTFS や NFSv4 の ACL に倣う。プロジェクトは既定でテナントの所属を受け継ぎ、これを継承と呼ぶ。その上に、プロジェクト単位の明示 ACE（`project_members` の行）が重なる。明示は継承より強く、テナントに行が無い利用者でも明示 ACE があるプロジェクトには入れる。この利用者を project-only のゲストと呼ぶ。継承元を外しても（テナント除名）、明示 ACE は独立して残る。

判定は「テナントに入れるか（継承）」、「プロジェクトに入れるか」の順に進む。明示 ACE を見るのは、継承で入れない場合に限る。

PAT に結び付けたテナント（複数あり得る）は「どのテナントを触れるか」の制限であって所属の証明ではない。セッションと PAT はどちらも同じ所属判定を通る。

関連するコードは `crates/service/src/access.rs`、`crates/handler/src/extractors.rs`、`crates/handler/src/auth_helpers.rs`、`crates/handler/src/handlers/tenant_members.rs`、`crates/handler/src/handlers/projects.rs`、`crates/handler/src/handlers/project_members.rs`、`crates/entity/src/tenant_members.rs` である。

## 継承と明示

ACL の概念と、この実装での表現の対応は次のとおりである。

| ACL の概念 | ここでの表現 | 意味 |
|---|---|---|
| 所有者 | `tenants.owner_id` | そのテナントの全プロジェクトに無条件で入れる。設定の変更と削除もできる。`tenant_members` に行は持たない |
| 継承（inherited） | `tenant_members` の行 | テナントに入れ、配下のプロジェクトに既定で入れる |
| 明示（explicit ACE） | `project_members` の行（`ProjectRole` 付き） | そのプロジェクトに、載った役で入れる。継承で入る人の役（メンバー）を上書きする。継承元と独立に残る |
| 継承の停止 | `projects.inherit_tenant_members` が偽（明示の操作） | 明示 ACE を持つ人だけに絞る。継承だけの人は入れない |

明示 ACE の持ち主がテナントに居ない状態が、project-only のゲスト（guest）である。ゲストは明示 ACE のあるプロジェクトの中だけ入れ、テナント全体のエンドポイントは開かない。

以前「所属の 3 層」と呼んでいた区分（オーナー、テナントメンバー、ゲスト）は、この表の所有者、継承のみ、明示のみに対応する。

### 除名が消すもの

テナント除名（`DELETE /v1/tenants/{id}/members/{user_id}`）が消すのは、継承（`tenant_members` の行）だけである。明示 ACE（`project_members` の行）は残る。明示 ACE は管理者が手で置いたものであり、継承元の変化を理由に黙って消すわけにはいかない。NTFS でグループから外してもファイルの explicit ACE が残るのと同じ理屈である。したがって、除名された人は残った明示 ACE のプロジェクトにゲストとして入り続ける。

例外は個人プロジェクト（Inbox）の本人の行である。この行は Inbox を初めて開いたときに `my_tasks::seed_personal_project_defaults` が自動で作るもので、管理者が置いた ACE ではない。在籍中の入口は `is_personal` 分岐（本人なら通す）が担うので、この行は継承が前提の付随物にすぎない。ゲストの判定（`access::is_shared_project_explicit_member`、`guest_tenant_ids`、`explicit_member_project_ids`、`list_explicit_projects`）はすべて個人プロジェクトを外す。除名された人は自分だった Inbox にも入れず、その行だけではテナント一覧にも出ず、2FA 強制の対象にもならない。

管理者が「除名したのにまだ入れる」と驚かないよう、`GET /v1/tenants/{id}/members/{user_id}/explicit-projects` でその人の明示 ACE（project_id、key、name、role）を確かめられる。除名の前に確かめるエンドポイントだが、対象がテナントに居るかは問わないので、除名の後に「まだ何が残っているか」を見るのにも使える。呼び出し側が入れないプロジェクトは名前や key を出さず、`hidden_count` に件数だけを載せる。テナント Admin でもプロジェクトの閲覧は `list_projects` と同じ境界で絞られる。閉め出したい場合は、そこに挙がったプロジェクトのメンバーからも外す。除名（`DELETE`）自体の応答は 204 で、body は持たない。

この定めは旧版（#688 以前）のデータにも遡って効く。旧版で除名された人の残存行も明示 ACE であり、デプロイ後はそのプロジェクトにゲストとして入れる。migration では消さない。理由は[決定の記録](#決定の記録)に書く。

### 継承の停止

NTFS と同じく、継承を止めるのは明示の操作である。プロジェクト設定のメンバーの画面で「テナントのメンバーを継承する」を切ると、`projects.inherit_tenant_members` が偽になる（[プロジェクトの公開規則](#プロジェクトの公開規則)）。明示 ACE を置いても継承は止まらない。明示 ACE は継承に足す用途（役を変える）だけに使う。

以前は、明示 ACE を 1 件置いた時点で暗黙に継承が止まっていた。役を付けるためにメンバーを載せただけで、他のテナントのメンバーと BOT が外れていたので、TASK-501 で改めた。

### ゲスト（project-only guest）の定め

- ゲストが入れるのは `project_members` に明示指定されたプロジェクトだけである。「テナントのメンバーを継承する」規則はテナントメンバー限りで、ゲストには開かない
- テナント全体のエンドポイントのうち、プロジェクト一覧（`GET /v1/tenants/{id}/projects`）と My Tasks（`GET /v1/tenants/{id}/users/me/tasks`）だけは、ゲストには自分が明示 member の project の分に絞って返す。公開 project は含めない。判定は `AuthUser::ensure_tenant_access_or_guest_scope` と `access::explicit_member_project_ids` に集約し、ハンドラーには散らさない
- その他のテナント全体のエンドポイント（テナント取得・メンバー一覧・Drive・テナント設定など）は 403 である。frontend は 403 を空表示・案内文で穏当に受ける（下の表）
- テナント一覧（`GET /v1/tenants`）にはゲストとして関わるテナントが `membership: "Guest"` を付けて出る（[テナント一覧の membership](#テナント一覧の-membership)）
- ゲストは 2 つの経路で生まれる。1 つはテナントに居ない利用者をプロジェクトへ直接招く経路（`project_members::add_member`。GitHub の outside collaborator に相当）である。もう 1 つはテナントメンバーへ明示 ACE を置いた後にテナントから外す経路で、残った `project_members` の行がゲストの指定になる。`list_explicit_projects` がその行を挙げる
- 招けるのはプロジェクト Admin・オーナー・そのプロジェクトに入れるテナント `Admin` だけである
- 通知・メンションの宛先には入らない（`project_accessible_user_ids` はテナント在籍者に絞る）
- Drive のファイル配信（`drive_files::can_access_project`）はゲストを通さない
- ゲストもテナントの `require_2fa`（2FA 強制）の対象である。`login_session::user_in_require_2fa_tenant` が `access::guest_tenant_ids` でゲストのテナントも見る
- 個人プロジェクト（Inbox）にはゲストとして入れない。本人の自動生成行は継承が前提で、除名の後は効かない（[除名が消すもの](#除名が消すもの)）

### frontend がテナント全体に対して呼ぶエンドポイントとゲストへの扱い

対応は次のとおりである。

| エンドポイント | frontend の呼び元 | ゲストへの扱い |
|---|---|---|
| `GET /v1/tenants` | stores/tenant.ts（TenantSwitcher の一覧）・useResolvedTenantId（URL の display_id から UUID を解決） | `membership` を Guest にして返す。テナント設定の欄は null |
| `GET /v1/tenants/{id}/projects` | api-vue-query の useProjectsQuery（AppSidebar の NavProjects・useResolvedProjectId の projectKey から UUID を解決）、ProjectCreateForm / DeleteProjectDialog / ProjectSettingsView（cache 更新） | **自分の明示 member の project に絞って 200** |
| `GET /v1/tenants/{id}/users/me/tasks` | pages/@tenant/my-tasks（テナント選択直後の着地） | **自分の project の分に絞って 200** |
| `GET /v1/tenants/{id}/members` | ProjectSettingsView の MembersSection | 403 のまま。MembersSection は 403 を「権限なし」表示で受け、画面は壊れない |
| `GET /v1/tenants/{id}/users/{user_id}` | pages/@tenant/users/@userId（タスクの担当者・コメント投稿者・メンバー一覧の名前から開く） | 403 のまま。画面は「閲覧できません」と出す |
| `GET /v1/tenants/{id}` | 呼び元なし（一覧で足りる） | 403 のまま |
| `GET /v1/tenants/{id}/users/me/personal-project` | 呼び元なし | 403 のまま |
| Drive 系（`/v1/tenants/{id}/drive...`） | テナント全体に対しては呼ばない | 403 のまま |

## `tenant_members`

列は次のとおりである。

| カラム | 型 | 説明 |
|---|---|---|
| `id` | `UUID` PK | |
| `tenant_id` | `UUID` NOT NULL | `tenants(id)` ON DELETE CASCADE |
| `user_id` | `UUID` NOT NULL | `users(id)` ON DELETE CASCADE |
| `role` | `VARCHAR` NOT NULL | `TenantRole`（`Admin` / `Member` / `Viewer`） |
| `department` | `TEXT` NULL | このテナント（会社）での部署。自由記述、100 文字以内 |
| `position` | `TEXT` NULL | このテナントでの役職。自由記述、100 文字以内 |
| `team` | `TEXT` NULL | このテナントでのチーム。自由記述、100 文字以内 |

`UNIQUE (tenant_id, user_id)` と `user_id` 単独の索引を張る。前者の索引は先頭列が `tenant_id` なので、`user_id` だけで引く経路（ログインごとに通る 2FA 強制の判定、テナント一覧）には効かない。

オーナーは `tenant_members` に行を持たないので、その所属は `tenants` の `owner_department` / `owner_position` / `owner_team`（`TEXT` NULL。形式は上の 3 列と同じ）に持つ。列の定義は [m20261104000000_tenants_owner_org_profile.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261104000000_tenants_owner_org_profile.rs) にある。

列の定義は [m20260818000000_tenant_members.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20260818000000_tenant_members.rs) と [m20261021000000_tenant_members_org_profile.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261021000000_tenant_members_org_profile.rs) にある。

### オーナーの所属

オーナーに `tenant_members` の行を足さないのは、その行が所属の判定そのものだからである。足すとオーナーが通知の宛先（`project_accessible_user_ids`）に入り、`would_drop_last_admin` の「在籍 Admin」にも数えられる。

読むときは `OrgProfile::resolve` を通す。所属行があれば行、無ければオーナーはテナントの列、それ以外は未設定である。オーナーにも実在の行があるとき（メンバー追加 API で足せる）は行が勝ち、テナントの列は読まれない。

オーナーの付け替えのエンドポイントは無い。作るときは、前のオーナーの所属を引き継がないように 3 列を空に戻す。

### ロール

各ロールの意味は次のとおりである。

| ロール | 現在の意味 |
|---|---|
| `Admin` | テナントメンバーの追加・ロール変更・削除と招待。共有プロジェクトの作成。**自分が入れる**共有プロジェクトの更新・削除・プロジェクトメンバー管理・Webhook 管理（オーナーと同等。TASK-372） |
| `Member` | テナントに入れる |
| `Viewer` | テナントに入れる（`Member` と同じ） |

ロールを見るのは上の管理系のエンドポイント（`require_tenant_admin` / `require_project_admin`）だけで、「入れるか」の判定（`has_tenant_access` と公開規則）は「行があるか」しか見ない。テナント `Admin` でも、明示 ACE で閉じたプロジェクトに ACE が無ければ入れないし管理もできない。個人プロジェクト（Inbox）はテナントロールでは管理できず、明示 ACE で入れていても管理できるのは本人とオーナーだけである。PAT の発行はロールを見ず、テナントに所属していれば許す（[個人アクセストークンの認可](https://docs.koyori.app/dev/design/personal-access-tokens-authz)）。

## 招待（`tenant_invitations`）

テナントに人を入れる経路は 2 つある。登録済みの利用者を UUID で足すメンバー追加 API と、メールアドレス宛ての招待である。招待はまだアカウントの無い人も呼べる。列は次のとおりである。

| カラム | 型 | 説明 |
|---|---|---|
| `id` | `UUID` PK | |
| `tenant_id` | `UUID` NOT NULL | `tenants(id)` ON DELETE CASCADE |
| `email` | `VARCHAR` NOT NULL | 宛先（`normalize_email` 済み） |
| `role` | `VARCHAR` NOT NULL | 承諾したときに付く `TenantRole` |
| `generation` | `INTEGER` NOT NULL | 世代。再送・再招待で 1 つ上げ、前のリンクを通らなくする |
| `invited_by` | `UUID` NOT NULL | `users(id)` ON DELETE CASCADE |
| `expires_at` | `TIMESTAMPTZ` NOT NULL | 発行・再送から 7 日 |
| `created_at` | `TIMESTAMPTZ` NOT NULL | |

`UNIQUE (tenant_id, email)`。承諾・取り消しで行を消すので、行があること = 保留中である。列の定義は [m20261002000000_tenant_invitations.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20261002000000_tenant_invitations.rs) にある。

規則は次のとおりである。

| 項目 | 規則 |
|---|---|
| トークン | 保存しない。招待 id と世代からサーバーの鍵で導く（`{招待 id}.{HMAC}`。`service::tenant_invitations::invitation_token`）。平文は DB にも apalis.jobs にも残らない |
| 送信ジョブ（`job::tenant_invitation_email`） | ペイロードは招待の id と世代だけである。同じ世代なら何度作っても同じリンクになるので、SMTP の応答だけが失敗して再試行されても、先に届いたメールのリンクは使える。処理時に招待の世代と違えば（後から再送・再招待された）送らないので、古いメールが新しいリンクを追い越さない |
| 発行・再送とジョブの投入 | 1 トランザクションで行う（`issue_and_enqueue` / `resend_and_enqueue`）。投入に失敗したら世代も戻り、前のリンクは生きたまま残る。取った送信の枠も返す |
| 二重招待 | 同じアドレスへの招待は同じ行を作り直す。ロール・期限・招待者を更新し、前のリンクを無効にする |
| 既にメンバー | オーナーを含め、そのアドレスの利用者がテナントに居れば 409（`already-member`）。発行・再送・承諾で確かめる。招待の後にメンバー追加 API で入った人の招待は残るので、再送でも見る。送信ジョブも送る前に確かめ、既にメンバーならメールを送らない（承諾が 409 になるリンクを外へ出さない） |
| 送信の間隔 | 同じテナント・同じアドレスへは 60 秒に 1 通（発行と再送で共通。超えると 429）。書き込みに失敗して枠を返すときは、取ったときの値と一致する場合だけ消す。期限切れの後に別のリクエストが取り直した枠を消さないためである |
| 送信の上限 | テナントごと・招待者ごとに 1 時間 50 通・1 日 200 通（固定窓。発行と再送で共通。超えると 429）。テナントは誰でも作れるので、宛先を変えながら送り続けてサービスの送信ドメインの評判を落とせないようにする。件名は固定（「テナントへの招待が届きました」）で、誰でも付けられるテナント名は本文にだけエスケープして出す |
| 期限切れ | 一覧には残す。画面で「期限切れ」と見せ、再送で延ばせる。承諾は 410 |
| 招待できるロール | `Admin` を含む全ロール。メンバー追加 API と同じく、テナント `Admin` が `Admin` を呼べる |
| 招待者が外されたら無効 | 承諾とその前のプレビューでは、招待者が今もオーナーかテナント `Admin` かを確かめ、違えば 404。降格・除名は保留中の招待に手を付けないので、外される前に出しておいた招待で戻れないようにする。承諾では書き込みと同じトランザクションで、テナント行と招待者のメンバー行を `FOR SHARE` で押さえてから見直す。確かめた直後の降格・除名・オーナーの付け替えは承諾の確定まで待たされる。送信ジョブも同じく確かめ、外された招待者の招待にはメールを送らない。再送では招待者を再送した人に替えるので、残った Admin が再送すれば使える招待に戻る |
| 承諾できる人 | 招待先のアドレスでログインしている本人だけ（セッション必須、メール確認済み）。リンクの転送だけで別人が入らないようにするためである。違えば 403（`invitation-email-mismatch`）。未登録の受け手は、そのアドレスで登録・メール確認・ログインを済ませてから同じリンクを開く |

## プロジェクトの公開規則

入れる人は次のとおりである。

| プロジェクトの状態 | 入れる人 |
|---|---|
| 継承する（`inherit_tenant_members` が真。既定） | そのテナントに入れる人全員（ゲストは含まない）。`project_members` に載っている人は、載った役で入る。その人がテナントに居なければゲストとして入る |
| 継承しない（`inherit_tenant_members` が偽） | 明示 ACE を持つ人だけ（＋テナントオーナー）。その人がテナントに居なければゲストとして入る |
| 個人プロジェクト（`is_personal = true`） | `personal_owner_id` の本人と、明示的に指定された人だけ（＋テナントオーナー）。継承の列は使わない |

既定で継承するのは、「参加したのにどのプロジェクトも見えない」状態と、役を付けるためにメンバーを載せただけで他の人が外れる状態を作らないためである。

個人プロジェクト（Inbox）は継承の対象外である。作成時は本人が `project_members` に入るが、その行は利用者の削除などで消えうる。行の有無にも継承の列にも頼らず、`is_personal` で明示的に閉じる。

この決まりは `service::access::tenant_member_can_enter` の一つに寄せている。入る検め（`project_is_open_or_member`）、一覧（`visible_project_ids`）、担当者の候補（`assignable_user_ids`）と担当者の検め（`require_project_access`）、通知とメンションの宛先（`project_accessible_user_ids`）は、すべてこの関数を呼ぶ。

ただしテナントオーナーは個人プロジェクトにも入れる。`has_tenant_access` がオーナーで短絡し、公開規則の判定に進まないためである（[継承と明示](#継承と明示)の表のとおり、オーナーは全プロジェクトに無条件で入れる）。一方で通知の宛先には入らない。`project_accessible_user_ids` は個人プロジェクトについて `personal_owner_id` だけを返す。読めるが通知は来ない、という非対称は意図したものである。

## 判定の実装

### 入口は 1 つ

ハンドラーは `AuthUser::ensure_tenant_access` だけを呼ぶ。これがセッション・PAT の双方を `has_tenant_access`（`extractors.rs`）に合流させる。例外はテナント一覧系の 2 エンドポイント（プロジェクト一覧・My Tasks）で、こちらは `ensure_tenant_access_or_guest_scope` を呼ぶ。通常判定に加えてゲストを通し、絞り込み用の project id 集合を返す。呼び方は次のとおりである。

```rust
auth.require_scope(Scope::ReadTask)?;
auth.ensure_tenant_access(&state, tenant_id, Some(project_id)).await?;
```

`has_tenant_access` の順序は次のとおりである。

1. テナントを取得する（無ければ 404）
2. オーナーなら、プロジェクト指定があればテナント配下かだけ確認して通す
3. `tenant_members` に行が無ければ、プロジェクトの指定があり `project_members` に明示指定がある場合（project-only のゲスト）に限りテナント配下確認の上で通す。それ以外は 403。存在探りを許さないため、明示指定の確認を実在確認より先に行う
4. プロジェクト指定があれば、そのプロジェクトがテナント配下かを確認する（違えば 404）
5. プロジェクトの公開規則で判定する

同じ判定を呼び出し側で重ねない。`require_project_access`（`auth_helpers.rs`）は `ensure_tenant_access` の部分集合なので、リクエスト元自身の認可に使うと同じクエリを二重に流すだけになる。担当者の追加など、自分以外を検証するときにだけ使う。

### `service::access` の主な関数

認可（handler）と通知の宛先抽出（service）が同じ規則を見る必要があるため、実装をここに集約している。

| 関数 | 用途 |
|---|---|
| `tenant_member_can_enter` | プロジェクトの公開規則そのもの。下の関数はすべてこれを呼ぶ |
| `is_tenant_member` | テナントに行があるか（オーナーは含まない） |
| `is_project_member` | `project_members` に明示指定があるか（公開規則は見ない）。ゲストの判定にも使う |
| `project_is_open_or_member` | 1 プロジェクトの公開規則。テナントに入れることは呼び出し側で確認済みの前提である |
| `visible_project_ids` | 一覧系。候補をまとめて 2 クエリで解決する（件数分のクエリを避ける） |
| `guest_tenant_ids` | ゲストとして関わるテナントの id 集合。テナント一覧の `membership` に使う |
| `explicit_member_project_ids` | テナント配下で明示指定されている project の id 集合。ゲストの一覧の絞り込みに使う |
| `project_accessible_user_ids` | 通知・メンションの宛先。テナントに残っている人だけに絞る |

### Drive は単純な置き換えをしない

Drive にはファイル ID だけで引ける経路がある（`GET /v1/drive/files/{id}/content`）。プロジェクト所属だけを見るとテナント境界を越えられるため、`can_access_project` はファイル自身の `tenant_id` に対してテナント所属を先に確認してからプロジェクト判定に進む。この経路はゲストを通さない。ゲストの層はタスク系 API のプロジェクトを指定する経路だけに効く。

## API と権限

テナント系エンドポイント（テナント一覧・取得・更新・削除、メンバー管理、招待の管理、ドライブ容量の設定）は、PAT に読みなら `read:tenant`、変更なら `write:tenant` を要求する。`api` / `read_api` の包含は[個人アクセストークンの認可](https://docs.koyori.app/dev/design/personal-access-tokens-authz)の含意の規則に書く。project 層のスコープ（`read:project` や `write:task` など）ではこれらのエンドポイントは開かない。

| 操作 | 許可 |
|---|---|
| テナント一覧（`GET /v1/tenants`） | 所属しているテナント＋ゲストとして関わるテナントを `membership` を付けて返す。PAT は、バインド先のテナントのうち同じ判定を通るものだけを返す |
| テナントの取得（`GET /v1/tenants/{id}`） | テナントに入れる人全員（ゲストは含まない） |
| プロジェクト一覧（`GET /v1/tenants/{id}/projects`） | owner は全件。member は公開規則どおり。ゲストは明示 member の分だけ |
| My Tasks（`GET /v1/tenants/{id}/users/me/tasks`） | 所属者には全体を返す。ゲストには自分の project の分に絞る |
| テナントの更新・削除 | オーナーのみ |
| メンバー一覧の閲覧 | テナントに入れる人全員（ゲストは含まない） |
| 利用者のプロフィール（`GET /v1/tenants/{id}/users/{user_id}`） | テナントに入れる人全員（ゲストは含まない）。対象はそのテナントのオーナー・メンバー・ゲストのいずれかで、それ以外は 404。返すのは id / username / account_kind / bio / avatar_url と、このテナントでの department / position / team（未設定・ゲストでは null）、このテナントとの関わり方の `membership`（`Owner` / `Member` / `Guest`）だけ。閲覧者はテナントに入れる人に限られるので、`membership` で誰がゲストかを見られるのはテナントのオーナー・メンバーだけである。PAT は `read:tenant` |
| メンバーの追加・ロールと所属（部署・役職・チーム）の変更・削除 | オーナー + テナント `Admin` |
| 所属行の無いオーナーの所属の変更 | オーナー本人のみ。ロールの変更と削除はオーナー本人でもできない |
| 招待の発行・一覧・再送・取り消し（`/v1/tenants/{id}/invitations`） | オーナー + テナント `Admin`。PAT は一覧に `read:tenant`、それ以外に `write:tenant` |
| 招待の中身を見る（`POST /v1/invitations/preview`） | トークンを持つ人（ログイン不要） |
| 招待の承諾（`POST /v1/invitations/accept`） | 招待先のアドレスでログインしている本人（セッションのみ） |
| プロジェクトの作成 | オーナー + テナント `Admin` |
| プロジェクトの更新・削除 | オーナー + そのプロジェクトに入れるテナント `Admin`（個人プロジェクトはオーナーのみ）。削除はセッション専用 |
| プロジェクトメンバーの管理・Webhook の管理 | オーナー + プロジェクト `Admin` + そのプロジェクトに入れるテナント `Admin`（個人プロジェクトはテナント `Admin` を通さない） |
| 継承の切り替え（`PUT /v1/tenants/{id}/projects/{project_id}` の `inherit_tenant_members`） | プロジェクトメンバーの管理と同じ人。メンバーの変更と同じロックの中で確かめる。個人プロジェクトは 400（`personal-project-inheritance`） |
| 担当者候補の一覧（`GET .../assignable-users`） | プロジェクトに入れる人。PAT は `write:task`。返すのは id / username / avatar_url と、このテナントでの department / team。department / team は未設定なら null で、プロフィールを読めない主体（ゲスト、`read:tenant` の無い PAT、プロジェクト限定の PAT）には全員 null で返す |
| 担当者候補の名前引き（`GET .../assignable-users?username=`） | 同上。ただし PAT は `read:task` でもよい |

一覧と取得で条件を揃えているのは、一覧に出るのに開けないテナントを作らないためである（#572）。ゲストのテナントは一覧に出るが取得は開かない、という非対称だけは意図して許した。`membership: "Guest"` がその見分けであり、クライアントはこの値で開けるエンドポイントを判断する。

### テナント一覧の membership

`GET /v1/tenants` は `TenantListItemResponse`（`TenantResponse` の全欄 + `membership`）を返す。`membership` は `TenantMembershipKind` で、`TenantRole` と同じ流儀の PascalCase 文字列（`Owner` / `Member` / `Guest`）である。取得・作成・更新のエンドポイントは `TenantResponse` を返す。ゲストにはテナント設定の欄（`owner_id` / `drive_quota_bytes` / `require_2fa`）を返さない（null）。

frontend は `membership` と `member_role` から、権限の無い操作を出さない。プロジェクトの作成（サイドバーの「+」と作成画面）は `Owner` と `Admin` にだけ出す。プロジェクト設定の一般の保存と削除は、共有プロジェクトでは `Owner` と `Admin`、個人プロジェクトでは `Owner` にだけ出す。サイドバーの「設定」は残し、ワークフロー・ラベル・カスタムフィールドなど、プロジェクトに入れる人に API が許す節へは入れるようにする。それでも拒否されたときは、403 を権限不足として表示する。

### 担当者候補のスコープ

担当者候補の 2 つでスコープが違うのは、返す量が違うためである。名前を指定しない形は「そのプロジェクトで担当者にできる利用者全員」を 1 リクエストで返すので、読むだけの主体に許すと利用者を列挙されてしまう。メンバー未指定の共有プロジェクトではテナント全体が返る。`username` を指定した形は呼び出し側が既に知っている名前と完全一致した 1 人だけを返し、外れたときも候補を出さない。担当者で絞ったタスク一覧は読むだけの操作なので、こちらは `read:task` で通す。

### メンバー系のレスポンスと更新

メンバー系レスポンス（`TenantMemberResponse` / `ProjectMemberResponse`）には表示用の `user`（`UserSummary`: id / username / avatar_url）を同梱する。メンバー管理 UI（#317）が ID とは別に利用者名・アバターを引けるようにするためで、メールアドレス等は含めない。`TenantMemberResponse` はこのテナントでの `department` / `position` / `team` も返す。オーナーの合成行（`from_owner`）では `tenants` の列の値（[オーナーの所属](#オーナーの所属)）を返す。

`PUT /v1/tenants/{id}/members/{user_id}`（`UpdateTenantMemberRequest`）は全欄省略可で、省略した欄（`None`）は変更しない。`role` を省略可にしているのは、所属だけを直す保存が古い `role` を送り返して、別の管理者による降格を巻き戻さないためである。部署・役職・チームは前後の空白を除き、空文字なら NULL に戻す。所属行の無いオーナーへの PUT は、本人が部署・役職・チームだけを送る場合に限り `tenants` の列を更新する。`role` を付けた PUT と本人以外の PUT は 404 で、何も保存しない。実在の行があるオーナーは、他のメンバーと同様に更新できる。UI では本人にだけ所属の編集を出し、ロール変更と除外は出さない。

## 守っている不変条件

不変条件とその実装は次のとおりである。

| 不変条件 | 実装 |
|---|---|
| 明示 ACE はテナント所属と独立に置ける | `project_members::add_member` はテナントに居るかを問わない（#568 の「プロジェクトメンバー ⊆ テナントメンバー」は #688 で外した）。継承だけがテナント所属に依る |
| 除名は継承を外すだけで、明示 ACE を消さない | `tenant_members::remove_member` は `project_members` の行を消さない。残る行は `list_explicit_projects` で確かめられる |
| 利用者を削除しても同じ（管理者による強制削除も明示 ACE を消さない） | `admin_users::delete_user_cascade` も `project_members` ではなく `tenant_members` の行を消す |
| テナントに居ない人の明示 ACE は、そのプロジェクトの中だけのゲストアクセスに限られる | `has_tenant_access` のゲスト分岐。テナント全体・Drive・通知には及ばない |
| 個人プロジェクトの自動生成行はゲストの入口にならない | `is_shared_project_explicit_member` / `guest_tenant_ids` / `explicit_member_project_ids` が `is_personal` を外す |
| テナントに居ない人に通知が飛ばない | `project_accessible_user_ids` がテナント在籍者との積集合を返す |
| テナントに居ない人がプロジェクトの Admin 枠を占有しない | `would_drop_last_admin` がテナントに残っている Admin だけを数える |
| プロジェクト側の操作が最後の在籍 Admin を落とさない | `would_drop_last_admin` が 409。ただし共有プロジェクトの最後の 1 行なら外せる（0 件になり継承へ戻る。管理はテナントオーナーが引き継ぐ）。個人プロジェクトは 0 件でも継承へ戻らないので 409。読みと書きの間に割り込まれないよう、プロジェクトメンバーの追加・更新・削除とテナントメンバーの除名が同じテナント行を `FOR UPDATE` で掴み（`project_members::lock_membership_changes`）、プロジェクトメンバーの追加・更新・削除は認可（`require_project_admin`）もロックの後に見る。テナント `Admin` の分岐は、ロックの外で済ませた可視性確認が古くなりうるので、ロック内で `project_is_open_or_member` を見直す |
| そのプロジェクトを管理できる人が常に居る | `require_project_admin` がテナントオーナーを無条件で通す。保証主体はオーナーだけである。テナント `Admin` は閉じたプロジェクトから締め出され、降格・除名もされうる |

明示 ACE を残すのは[継承と明示](#継承と明示)の定めによる。副次的に、除名した人を戻したときに元の割り当てがそのまま復元され、その人しか指定されていなかったプロジェクトが 0 件になって継承へ戻ることも防ぐ。閉め出したい場合はプロジェクトメンバーからも外す（`list_explicit_projects` が対象を挙げる）。

「最後の Admin を残す」判定は数えてから書くので、掴まないと 2 通りの抜け方がある。同じプロジェクトで互いを降格させ合う経路と、降格が「まだ居る」と読んだ後・書く前にその相手が除名される経路である。後者はプロジェクト行を掴んでも守れない。判定が読むのは `tenant_members` でもあるので、ロックはテナント行 1 つに寄せている。最後の 1 行の削除が「他の行は無い」と読んだ後に追加が通ると、Admin の居ない明示 ACE（Viewer だけ）が残るので、追加も同じロックを取る。同じテナントの別プロジェクトのメンバー操作まで待たされるが、管理操作は頻度が低い。

### 「在籍 Admin が 1 人以上」は不変条件ではない

直列化しても「A を降格してから、別の操作として B を除名」の順は両方とも正当なので、在籍している Admin が 0 人になることはある。除名側で数え直して 409 にすれば揃うが、対象が単独 Admin のプロジェクトを全部直すまでテナントから外せなくなり、退職者のオフボーディングが止まる。`admin_users::delete_user_cascade`（管理者による強制削除）はそもそも 409 を返せないので、止めても同じ状態には到達する。

この状態は行き止まりではない。テナントオーナー（開いたプロジェクトならテナント `Admin` も）がそのプロジェクトのメンバーを直せる。`would_drop_last_admin` が在籍者だけを数えるのは、この状態から復旧できるようにするためである。行数で数えると、もう操作できない人が最後の枠を占有して復旧できなくなる。

## HTTP ステータス

状況ごとのステータスは次のとおりである。

| 状況 | ステータス |
|---|---|
| 未認証 | 401 |
| テナントに入れない / プロジェクトに入れない / ロール不足 | 403 |
| テナントが存在しない / プロジェクトがそのテナントの配下にない | 404 |
| プロフィールの対象がそのテナントに関わっていない / 存在しない | 404（`users` はテナント横断の表なので、403 にして実在を明かさない） |
| 同じ利用者を二重に追加した / 既にメンバーの人を招待・承諾した | 409 |
| 招待の期限が切れている | 410 |
| 同じアドレスへ 60 秒以内に招待を送ろうとした | 429 |
| 最後の Admin を削除・降格しようとした（共有プロジェクトの最後の 1 行を削除する場合を除く） | 409 |

## 未実装と既知の制限

項目と現状は次のとおりである。

| 項目 | 現状 |
|---|---|
| 既存データの移行 | 行わない。`tenant_members` は空の状態から始まるため、非オーナーの利用者は API でメンバー登録するまでテナントに入れない |
| ゲストの招待 UI | frontend のプロジェクト設定（MembersSection）はテナントメンバーからしか選べない。テナント外の利用者を招くのは API を直接呼ぶ |
| ゲストの招待を締めるフラグ | 無い。プロジェクト Admin と入れるテナント `Admin` なら誰でもゲストを招ける。テナント設定で締めるのは別 Issue で扱う |
| ゲストへの通知 | 飛ばない。`project_accessible_user_ids` がテナント在籍者に絞るため、プロジェクトには入れるのに通知が来ない非対称は既知である |
| `Viewer` ロール | 「所属している」以上の意味を持たない。読み取り専用の制限は未実装である。書き込みの制限は全ハンドラーに波及するため未着手である |
| テナント `Admin` の権限 | 共有プロジェクトの作成と、入れる共有プロジェクトの管理まで（[API と権限](#api-と権限)の表）。閉じたプロジェクトに ACE が無ければ入れず管理もできない。個人プロジェクトは対象外である。開いたプロジェクトを閉じる（継承を切る）ときは**自分の ACE を先に置く**こと。置かずに切ると自分が締め出され、オーナーに直してもらうことになる。自動で自分を足すことはしない。降格の即時失効は保証しない（認可時点で許されていた進行中の要求は完了しうる） |
| フォルダ共有 | テナントから外しても `drive_folder_shares` は失効しない。共有は所属とは独立した明示的な付与として扱っている |
| 管理 UI | プロジェクトメンバーは frontend 実装済み（#317。プロジェクト設定のメンバー節）。テナントメンバーはテナント設定のメンバーページ（ロール変更・所属の編集・除外・メールでの招待）。CLI は未実装である |
| ゲストからのプロフィール閲覧 | できない（403）。同じプロジェクトの人に絞って開く規則は持っていない |
| 招待と登録の停止 | 管理者が新規登録を止めている（`user_registration_enabled = false`）と、未登録の受け手は招待を承諾できない |

## 決定の記録

| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-09-06 | 旧版で除名された人の残存行を migration で消さず、明示 ACE として扱う（#688 レビューの P1 に対する裁定） | 残存行は管理者が明示的に置いた ACE であり、継承の消滅を理由に無効にする根拠が無い |
| 2026-09-05 | ゲストへのプロジェクト一覧と My Tasks は 403 をやめ、自分が明示 member の project に絞って返す（#688 レビュー） | frontend の project 解決（URL の projectKey から UUID）とテナント選択直後の着地（My Tasks）がこの 2 つの一覧に依存しており、UI 用のエンドポイントを新設するより一覧を絞る方が判定を一箇所に保てる。当初は 403 を採っていた |
| 2026-10-21 | 共有プロジェクトの最後のメンバーは Admin でも外せる（TASK-217）。他の行が残る削除・単独 Admin の降格・個人プロジェクトは 409 のまま | 0 件にして継承へ戻す手段として |
| 2026-10-21 | 会社での情報（部署・役職・チーム）は `users` ではなく `tenant_members` に持ち、テナント `Admin` / オーナーが編集する。本人による編集は未対応（TASK-334） | 記録なし |
| 2026-10-25 | テナント `Admin` に共有プロジェクトの作成と、入れる共有プロジェクトの更新・削除・メンバー管理・Webhook 管理を許す（TASK-372）。見える範囲は変えず、個人プロジェクトは対象外 | 作成者を ACE に入れる案と継承フラグを足す案は退けた。退けた理由は記録なし |
| 2026-11-02 | 担当者候補に部署・チームを載せ、担当者欄でまとめて選べるようにする（TASK-396）。担当者の API とデータモデルは変えず、フロントが利用者 ID に開いて送る | 候補の一覧はプロフィールより広い主体が通るので、部署・チームはプロフィールを読める主体にだけ返し、候補そのものは従来どおり返す |
| 2026-11-04 | オーナー本人が自分の部署・役職・チームを設定できるようにし、`tenants` の列に保存する（TASK-443）。他の人によるオーナーの所属の編集は開かない | `tenant_members` に行を足す案は、通知の宛先と在籍 Admin の数え方が変わるので退けた |
| 2026-11-11 | プロジェクトにテナントのメンバーを継承するかの真偽（`inherit_tenant_members`）を持たせ、既定で継承する。明示 ACE を置いても継承は止まらず、載せた人は載せた役で入る。既存のプロジェクトはすべて継承する形に移す（TASK-501）。TASK-217 の「最後の 1 行は Admin でも外せる」は、継承するプロジェクトに限って残す | 役を付けるためにメンバーを載せただけで、他のテナントのメンバーと BOT（TASK-407）が外れていた。載せると他が外れる否定の形をやめ、NTFS の継承属性と同じく継承の停止を明示の操作にする。今までの絞りは役を付けるために生まれた物で意図した物ではないと見て、移しでは継承に寄せる |

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