# 🛠️ 設計・実装
## 非機能要件

 - **モジュール性**: モジュラモノリスの各モジュールが簡単にマイクロサービスに移行できること
 - **変更容易性**:
   - 権限を簡単に増やしたり、減らしたりできること
   - ロールを簡単に増やしたり、減らしたりできること
 - **拡張性**: 固定の RBAC で始めて、あとから動的な RBAC (テナントごとに作れるロール) にしても作り直さずに済むこと
 - **自己完結性**: ユーザーのロール・権限を都度問い合わせずに判定できること
 - **リアルタイム性**: 権限やロールが変わった時にできるだけ早く反映できること
 - **置換性**: IDaaS を差し替えても、権限の仕組みを作り直さずに済むこと
 - **安全性**: ロールを付けたり作ったりするときに、自分が持たない権限を与えられない (権限の昇格を防げる) こと

---
## 設計案
### 1. 集中型 (Clerk型)
クラスやファイル、1モジュール(マイクロサービス)でロールと権限を一元管理する方式。権限を増やすたびに更新が必要になる。

> Clerk との違い: Clerk はロールと権限をダッシュボードのデータで持ち、確かめるときは Clerk に問い合わせず、セッショントークンに載った権限 (`fea`・`o.per`・`o.fpm` から組み立てる) を読む。

```mermaid
flowchart LR
  project("📁 project モジュール")
  other("🧩 ほかの機能のモジュール")
  subgraph tenant ["🏢 tenant モジュール"]
    role(["👔 Role<br/>owner・admin・member"])
    projectPermission(["🔑 project.create・project.delete"])
    tenantPermission(["🔑 tenant.update"])
    otherPermission(["🔑 ほかの機能の権限"])
    role -->|権限を束ねる| projectPermission & tenantPermission & otherPermission
  end
  project -->|"リクエストのたびに<br/>project.delete をできるか"| tenant
  other -->|リクエストのたびに問い合わせる| tenant

  user(("👤 ユーザー")) --> project & other
```

<details><summary>実装例</summary>

```python
# backend/src/tenant/domain/model/membership/permission.py


class Permission(Enum):
    # テナント
    TENANT_UPDATE = "tenant.update"  # テナントの名前・設定を変える
    TENANT_DELETE = "tenant.delete"  # テナントを削除する
    # 課金
    BILLING_MANAGE = "billing.manage"  # プランを変える・請求を見る
    # メンバー
    MEMBERSHIP_INVITE = "membership.invite"  # メンバーを招待する・招待を取り消す
    MEMBERSHIP_CHANGE_ROLE = "membership.change_role"  # メンバーのロールを変える
    MEMBERSHIP_REMOVE = "membership.remove"  # メンバーを外す
    # プロジェクト (project モジュール)
    PROJECT_CREATE = "project.create"
    PROJECT_DELETE = "project.delete"


# backend/src/tenant/domain/model/membership/role.py


class Role(Enum):
    # (permissions と __new__ は今と同じ)

    # すべての権限を持つので、足した権限も書かずに済む
    OWNER = ("owner", frozenset(Permission))
    ADMIN = (
        "admin",
        frozenset(
            {
                Permission.TENANT_UPDATE,
                Permission.MEMBERSHIP_INVITE,
                Permission.MEMBERSHIP_CHANGE_ROLE,
                Permission.MEMBERSHIP_REMOVE,
                Permission.PROJECT_CREATE,
                Permission.PROJECT_DELETE,
            }
        ),
    )
    MEMBER = ("member", frozenset({Permission.PROJECT_CREATE}))
```

</details>

### 2. 分散型 (IDDD型)
各モジュールが自分の権限を持ち、ロールだけを tenant モジュールに問い合わせて自分の Role に訳す方式。ロールを増やすたびに、そのロールに権限を許すモジュールの Role の写しも更新が必要になる (写しに無いロールは拒否する)。

> IDDD との違い: IDDD は権限を持たず、「この人は Moderator ロールか」を問い合わせて、`Moderator` などの値オブジェクトに訳す。

```mermaid
flowchart LR
  subgraph project ["📁 project モジュール"]
    projectRole(["👔 Role (tenant のロールの写し)<br/>owner・admin・member"])
    projectPermission(["🔑 Permission<br/>project.create, ..."])
    projectRole -->|権限を束ねる| projectPermission
  end
  subgraph other ["🧩 ほかの機能のモジュール"]
    otherRole(["👔 Role (tenant のロールの写し)"])
    otherPermission(["🔑 Permission"])
    otherRole -->|権限を束ねる| otherPermission
  end
  subgraph tenant ["🏢 tenant モジュール"]
    role(["👔 Role<br/>owner・admin・member"])
    permission(["🔑 Permission<br/>tenant.update, ..."])
    role -->|権限を束ねる| permission
  end
  project -->|"リクエストのたびに<br/>この人のロールは何か"| tenant
  other -->|リクエストのたびに問い合わせる| tenant

  user(("👤 ユーザー")) --> project & other
```

<details><summary>実装例</summary>

```python
# 各モジュールごとに定義


class Role(Enum):
    """tenant のロールを、このモジュールで使う形に訳したもの。ACL アダプターが tenant の公開 IF から作る"""

    OWNER = "owner"
    ADMIN = "admin"
    MEMBER = "member"


class Permission(Enum):
    """プロジェクトの操作と、それを許すロール"""

    roles: frozenset[Role]

    def __new__(cls, value: str, roles: set[Role]) -> Self:
        # Role と同じく、value は文字列のままにする。許すロールが同じ操作が、別名にまとめられないため
        permission = object.__new__(cls)
        permission._value_ = value
        permission.roles = frozenset(roles)
        return permission

    # プロジェクト
    PROJECT_CREATE = ("project.create", {Role.OWNER, Role.ADMIN, Role.MEMBER})
    PROJECT_DELETE = ("project.delete", {Role.OWNER, Role.ADMIN})
```

</details>

### 3. 合流型 (Kubernetes型)
各モジュールが自分の権限と、それを許すロールの名前を宣言し、起動時に tenant モジュールへ集める方式。機能を足しても tenant モジュールは変えずに済む。tenant モジュールがすべての権限を知るので、集中型と同じく、ロールを DB に移せばテナントごとに作るロールも扱える (宣言した許すロールは、既定のロールの中身になる)。owner には tenant モジュールがすべての権限を許すので、宣言には書かない。

確かめ方は、次の 2 つから選べる。tenant モジュールのロールと権限はどちらも同じで、違うのは確かめる所だけ。

 - **tenant に聞く**: 各モジュールは「この人は project.delete をできるか」を tenant モジュールに聞き、tenant モジュールが確かめる
 - **権限の集合を受け取る**: 各モジュールは「この人の権限の集合」を tenant モジュールから受け取り、要る権限があるかを自分で確かめる。トークンに権限の集合を載せるときは、こちらになる

> Kubernetes との違い: Kubernetes はコントロールプレーンのコントローラーが、ラベル (`aggregate-to-admin` など) の付いた ClusterRole を動いている間ずっと合流させる。ここでは起動時に 1 回集めるだけ。

```mermaid
flowchart LR
  user(("👤 ユーザー"))
  subgraph project ["📁 project モジュール"]
    projectPermission(["🔑 project.create → admin・member<br/>project.delete → admin"])
  end
  subgraph other ["🧩 ほかの機能のモジュール"]
    otherPermission(["🔑 権限 → 許すロール"])
  end
  subgraph tenant ["🏢 tenant モジュール"]
    role(["👔 Role<br/>owner・admin・member"])
    permission(["🔑 tenant.update<br/>project.create・project.delete (合流)"])
    role -->|権限を束ねる| permission
  end
  user --> project & other
  project -.->|起動時に宣言を渡す| tenant
  other -.->|起動時に宣言を渡す| tenant
  project -->|"リクエストのたびに<br/>project.delete をできるか<br/>(または この人の権限の集合)"| tenant
  other -->|リクエストのたびに問い合わせる| tenant
```

<details><summary>実装例</summary>

```python
# project モジュール: 権限と、それを許すロールの名前を宣言する。起動時に AppModule.permissions で tenant に集める


class Permission(Enum):
    # (roles と __new__ は 2 と同じ形。tenant の Role は import できないので、ロールは名前で書く)

    PROJECT_CREATE = ("project.create", {"admin", "member"})
    PROJECT_DELETE = ("project.delete", {"admin"})


# project モジュール (tenant に聞く): tenant に「この人は project.delete をできるか」を聞く

if not permission_service.can(tenant_id, user_id, Permission.PROJECT_DELETE):
    raise SystemException(
        ErrorCode.PERMISSION_DENIED, f"permission={Permission.PROJECT_DELETE.value}"
    )


# project モジュール (権限の集合を受け取る): tenant から「この人の権限の集合」を受け取り、自分で確かめる

# 例: {"tenant.update", "project.create", "project.delete"}
permissions = permission_service.permissions_of(tenant_id, user_id)
if Permission.PROJECT_DELETE.value not in permissions:
    raise SystemException(
        ErrorCode.PERMISSION_DENIED, f"permission={Permission.PROJECT_DELETE.value}"
    )


# tenant モジュール: 確かめ方に合わせて、できるかだけを答えるか、権限の集合をそのまま返す


def can(self, tenant_id: TenantId, user_id: UserId, permission: Enum) -> bool:
    # 各モジュールの権限の Enum を受け取り、値の文字列で権限の集合と比べる
    return permission.value in self.permissions_of(tenant_id, user_id)


def permissions_of(self, tenant_id: TenantId, user_id: UserId) -> frozenset[str]:
    membership = self.__membership_repository.membership_of(tenant_id, user_id)
    if membership is None:
        return frozenset()
    # ② の Role。権限の値の文字列の集合を持つ
    role = self.__role_repository.role_of(membership.role_id)
    return role.permissions if role is not None else frozenset()
```

</details>

---
## 比較検討

◯ 設計案のとおりで満たす・△ 手を加えれば満たす・× 作り直さないと満たせない

| 非機能要件 | 1. 集中型 (Clerk型) | 2. 分散型 (IDDD型) | 3. 合流型 (Kubernetes型) |
|:--|:-:|:-:|:-:|
| モジュール性 | △ | ◯ | △ |
| 変更容易性 (権限) | × | ◯ | ◯ |
| 変更容易性 (ロール) | ◯ | × | △ |
| 拡張性 | ◯ | × | ◯ |
| 自己完結性 | △ | △ | △ |
| 安全性 | ◯ | × | ◯ |

<details><summary><b>1. 集中型 (Clerk型)</b></summary>

- メリット
  - ロールを足す・減らすのは tenant の Role だけ (変更容易性 (ロール))
  - tenant がすべての権限を知っているので、ロールを DB に移せば動的な RBAC にできる。各モジュールは変えない (拡張性)
  - tenant がすべての権限を知るので、ロールを付けるときの権限の昇格の確認がすべての権限に効く (安全性)
  - ロールと権限の一覧が 1 か所にあり、見通しがよい
- デメリット
  - 移す作業は問い合わせる先を tenant の API に替えるだけだが、移したモジュールの権限は tenant に残る。機能を足すたびに tenant も一緒にリリースすることになり、独立してリリースできない (モジュール性)
  - 機能を足すたびに、機能のモジュールと tenant の両方を変える。機能のモジュールだけで済ませるには、権限を各モジュールに移す作り直しになる (変更容易性 (権限))
  - 動的な RBAC にすると、消した権限の文字列がカスタムロールに残るので、読むときに落とす処理が要る (拡張性)

</details>

<details><summary><b>2. 分散型 (IDDD型)</b></summary>

- メリット
  - tenant に聞くのはロールだけなので、問い合わせる先を tenant の API に替えればマイクロサービスに分けられる (モジュール性)
  - 権限を足す・減らすのは機能のモジュールだけ (変更容易性 (権限))
  - 確かめるのに要るのはロール 1 つなので、トークンに載せても小さい (自己完結性)
- デメリット
  - ロールを足す・減らすと、tenant の Role と、そのロールに権限を許すモジュールの Role の写し・訳を変える。マイクロサービスに分けたあとは、それらを一緒にリリースする。tenant だけで済ませるには、ロールに許す権限を tenant に移す作り直しになる (変更容易性 (ロール))
  - 各モジュールはコードにあるロールにしか訳せないので、テナントごとのロールを扱えない (拡張性)
  - tenant は機能の権限を知らないので、ロールを付けるときの権限の昇格の確認が、tenant の権限にしか効かない。機能の権限は、「ロール X に許すなら、X を付けられるロールにも許す」という手の決まりで守るしかない (安全性)

</details>

<details><summary><b>3. 合流型 (Kubernetes型)</b></summary>

- メリット
  - 権限を足す・減らすのは機能のモジュールの宣言だけで、tenant は変えない (変更容易性 (権限))
  - tenant がすべての権限を知るので、ロールを DB に移せば動的な RBAC にできる。各モジュールは変えない (拡張性)
  - tenant がすべての権限を知るので、ロールを付けるときの権限の昇格の確認がすべての権限に効く (安全性)
  - 書き間違えたロールの名前や、重なった権限を起動時に見つけられる
  - 権限の集合を受け取る確かめ方なら、1 リクエストで 1 回受け取れば、何度確かめても問い合わせ直さずに済む。画面に「できる操作」もそのまま返せる
- デメリット
  - 起動時の合流は 1 つのプロセスの中でしか効かない。マイクロサービスでは、デプロイ時に tenant へ権限を登録する仕組みが要る (モジュール性)
  - 既定のロールを足すと、tenant の Role と、そのロールに許す権限を宣言しているモジュールを変える (変更容易性 (ロール))
  - 動的な RBAC にすると、消した権限の文字列がカスタムロールに残るので、読むときに落とす処理が要る (拡張性)
  - fastship-py の `AppModule` に、権限の宣言を足す必要がある

</details>

<details><summary><b>どの案にも当てはまること</b></summary>

- 図のとおりなら、どの案もリクエストのたびに tenant に問い合わせる。問い合わせずに確かめるには、トークンに載せる。載せるのは、2 はロール、1・3 は権限の集合で、権限が増えるほど大きくなる (自己完結性)
- トークンは、所属するテナントの数でも大きくなる。Clerk のように、選んでいるテナントの分だけ載せる (自己完結性)
- 問い合わせる形なら、ロールの付け替えはすぐ効く。トークンに載せると、トークンが切れるまで効かない。自己完結性とは引き換えになる (リアルタイム性)
- IDaaS から受け取るのはユーザー ID だけで、ロールと権限は tenant に持つ。トークンに載せるときも、IDaaS のカスタムクレームではなく自前で発行するトークンに載せれば、IDaaS を差し替えられる (置換性)

</details>

---
## 実装
3. 合流型を、権限の集合を受け取る確かめ方で作る。各モジュールは権限と一緒に既定のロールを公開し、新しい権限を既定のロールに紐付けるのは、権限を足すモジュール自身にする。権限だけを公開すると、機能を足すたびに tenant モジュールの紐付けを変えることになり、集中型と同じ困りごとに戻るため。

| | モジュラモノリス | マイクロサービス |
|:--|:--|:--|
| tenant が全モジュールの権限を集める | 起動時に `CompositeModule.permissions` から | 各サービスのデプロイのたびに、新しい版の `GET /internal/permissions` から |
| 各モジュールが権限の集合を受け取る | tenant モジュールから、同じプロセスの中で | 内部通信トークンのクレームから |

マイクロサービスでは、足した権限はトラフィックを新しい版に流す前に取り込み、発行済みのトークンが切れるのを待つ。先に流すと、取り込むまでとトークンが切れるまで、足した権限を要る操作が owner も含めて拒否される。消した権限は、古い版がまだ確かめているので、流した後に落とす。

```mermaid
sequenceDiagram
  autonumber
  participant CI as CI (project のデプロイ)
  participant P as project サービス (新しい版)
  participant T as tenant サービス
  participant B as 入口 (BFF)

  CI->>P: トラフィックを流さずにデプロイする
  CI->>T: project の権限を取り込む (足すだけ)
  T->>P: GET /internal/permissions
  P-->>T: project.create (既定: admin・member)<br/>project.delete (既定: admin)
  T->>T: DB の一覧に足す (取れなければ前回の一覧のまま)
  CI->>CI: 内部通信トークンの寿命 (5 分) を待つ
  CI->>P: トラフィックを新しい版に流す
  CI->>T: project の権限を取り込み直す (新しい版に無い権限を落とす)
  B->>T: IDaaS のトークンと、選んでいるテナント
  T-->>B: 内部通信トークン (permissions クレーム)
  B->>P: DELETE /{tenant_id}/projects/{project_id}<br/>+ 内部通信トークン
  P->>P: tenant_id がトークンと同じで、permissions に project.delete があるか
```

### ① 各モジュール: 権限と既定のロールを宣言し、公開する
権限の Enum の基底 (fastship-py の `Permission`。モジュールの `Permission` と名前が重なるので `_Permission` として import する)、`AppModule.permissions` と、それを JSON にして返す `GET /internal/permissions` は fastship-py に足す。

権限の Enum はドメインに置かない。使うのはルート・ツールの門と `core.py` で、ルート (`port.adapter.resource`) やツール (`port.adapter.tool`) は lint-imports の規約で domain を import できないため。

```python
# project/permission/rbac.py


@unique  # 値が重なると別名になり、2 つ目の既定のロールが黙って捨てられるため
class Permission(_Permission):
    # プロジェクト
    PROJECT_CREATE = ("project.create", {"admin", "member"})
    PROJECT_DELETE = ("project.delete", {"admin"})


# project/core.py


class Project(AppModule):
    @property
    @override
    def permissions(self) -> list[_Permission]:
        return list(Permission)
```

### ② tenant: 全モジュールの権限を集め、ロールを組み立てる

```python
# tenant/domain/model/permission/permission.py


@dataclass(frozen=True)
class Permission:
    """全モジュールの権限の 1 件。モジュラモノリスでは各モジュールの Permission から、マイクロサービスでは JSON から作る。

    tenant/permission/rbac.py の Permission (tenant 自身の権限の Enum) とは別物。1 つのファイルで両方は import しない
    """

    value: str  # 「リソース.操作」
    # 既定のロールの名前。owner は書かない (すべての権限を持つ)
    default_roles: frozenset[str]


# tenant/domain/model/permission/permission_catalog.py


class PermissionCatalog(abc.ABC):
    """全モジュールの権限の一覧。モジュラモノリスでは、起動時の CompositeModule.permissions から作る"""

    @abc.abstractmethod
    def permissions(self) -> list[Permission]: ...


# tenant/port/adapter/service/permission/http_permission_catalog.py (マイクロサービス)


class HttpPermissionCatalog(PermissionCatalog):
    def refresh(self, service: str, url: str, *, prune: bool) -> None:
        """service の権限を、新しい版の url から取り込む。CI がデプロイの中で 2 回呼ぶ。

        トラフィックを流す前は prune=False で足すだけにし、流した後に prune=True で、新しい版に無い権限を落とす
        """
        permissions = self.__client.get(f"{url}/internal/permissions")
        # 重なった権限や知らない既定のロールがあれば、取り込まずに止める (CI が落ちる)
        validate(permissions, self.__repository.all_except(service))
        # 取れなかった・止めたときは DB を書き換えない。消えたと扱うと、カスタムロールからも落ち、全員がその権限を失う
        if prune:
            self.__repository.replace(service, permissions)
        else:
            self.__repository.merge(service, permissions)

    @override
    def permissions(self) -> list[Permission]:
        return self.__repository.all()


# tenant/domain/model/role/role.py

# owner はすべての権限を持つので、宣言には書かない
BUILT_IN_ROLE_NAMES = ("admin", "member")


@dataclass(frozen=True)
class Role:
    """権限の集合。既定のロール (固定) もカスタムロール (動的) も、同じ形で持つ"""

    id: RoleId  # 既定のロールは名前 (owner・admin・member)、カスタムロールは UUID
    name: str
    permissions: frozenset[str]  # 権限の値。トークンにそのまま載せる

    def covers(self, other: Role) -> bool:
        """other の権限をすべて持つか。ロールを付ける・作るときに確かめ、権限の昇格を防ぐ"""
        return other.permissions <= self.permissions

    @staticmethod
    def built_in(permissions: list[Permission]) -> list[Role]:
        """既定のロールを、全モジュールの宣言から組み立てる。DB には入れない"""
        owner = Role(
            RoleId("owner"),
            "owner",
            frozenset(permission.value for permission in permissions),
        )
        return [owner] + [
            Role(
                RoleId(name),
                name,
                frozenset(
                    permission.value
                    for permission in permissions
                    if name in permission.default_roles
                ),
            )
            for name in BUILT_IN_ROLE_NAMES
        ]

    @staticmethod
    def custom(
        role_id: RoleId,
        name: str,
        stored: frozenset[str],
        permissions: list[Permission],
    ) -> Role:
        """カスタムロールを DB から組み立てる。一覧に無い権限 (消した権限) は落とす"""
        return Role(
            role_id,
            name,
            stored & frozenset(permission.value for permission in permissions),
        )
```

### ③ tenant: 内部通信トークンを発行する

```python
# tenant/application/token/token_application_service.py


class TokenApplicationService:
    def issue(self, id_token: str, tenant_id: str) -> str:
        """IDaaS のトークンを、選んでいるテナントの権限の集合を載せた内部通信トークンに替える。入口 (BFF) が呼ぶ"""
        # IDaaS から受け取るのはユーザー ID だけ
        user_id = self.__identity_provider.verify(id_token)
        membership = self.__membership_repository.membership_of(
            TenantId(tenant_id), user_id
        )
        if membership is None:
            raise SystemException(
                ErrorCode.PERMISSION_DENIED,
                f"tenant_id={tenant_id} user_id={user_id.value}",
            )
        # 既定のロールは PermissionCatalog から、カスタムロールは DB から
        role = self.__role_repository.role_of(membership.role_id)
        # 消したカスタムロールが付いたままのときも、500 にせず拒否する
        if role is None:
            raise SystemException(
                ErrorCode.PERMISSION_DENIED, f"role_id={membership.role_id.value}"
            )
        return self.__token_signer.sign(
            # 選んでいるテナントの分だけ載せ、所属するテナントの数でトークンが大きくならないようにする
            {
                "sub": user_id.value,
                "tenant_id": tenant_id,
                "permissions": sorted(role.permissions),
            },
            # 短いほどロールの付け替えが早く効き (リアルタイム性)、長いほど tenant に問い合わせずに済む (自己完結性)
            expires_in=timedelta(minutes=5),
        )
```

### ④ 各モジュール: 権限の集合で判定する
ルートの門 (`GetCurrentUser`) と、権限の集合を取るポート (`PermissionSource`) は fastship-py に足す。門は、path の `tenant_id` のテナントに所属していなければ 404 (テナントがあることを伏せる)、権限の集合に要る権限が無ければ 403 で拒否する。構成で替わるのは `PermissionSource` の実装だけで、ルートは変わらない。

 - **モジュラモノリス**: IDaaS のトークンを確かめ、tenant モジュールから同じプロセスの中で取る
 - **マイクロサービス**: 内部通信トークンを tenant の公開鍵 (JWKS) で確かめ、クレームから取る。path の `tenant_id` がクレームと違えば、所属していないときと同じく 404 で拒否する

```python
# project/port/adapter/resource/project/project_resource.py


@router.delete("/{tenant_id}/projects/{project_id}")
def delete_project(
    project_id: str,
    current_user: Annotated[
        CurrentUser, Depends(GetCurrentUser(Permission.PROJECT_DELETE))
    ],
) -> None:
    # 門が確かめるのは「tenant_id のテナントで、その権限があるか」だけ。
    # プロジェクトは必ず current_user.tenant_id で絞って取る (ほかのテナントのプロジェクトの ID を指定されても消さない)
    ...
```