docs/plans/2026-03-17-space-permission-cascading-design.md

@@ -0,0 +1,226 @@
+# Space Permission Cascading — Design Document
+
+**Date:** 2026-03-17
+**Status:** Approved
+
+## Overview
+
+Server-side feature that allows user rights in a Space to cascade down to its
+direct child rooms. Includes power level cascading and role-based room access
+control. Enabled via a server-wide configuration flag, disabled by default.
+
+## Requirements
+
+1. Power levels defined in a Space cascade to all direct child rooms (Space
+   always wins over per-room overrides).
+2. Admins can define custom roles in a Space and assign them to users.
+3. Child rooms can require one or more roles for access.
+4. Enforcement is continuous — role revocation auto-kicks users from rooms they
+   no longer qualify for.
+5. Users are auto-joined to all qualifying child rooms when they join a Space or
+   receive a new role.
+6. Cascading applies to direct parent Space only; no nested cascade through
+   sub-spaces.
+7. Feature is toggled by a single server-wide config flag
+   (`space_permission_cascading`), off by default.
+
+## Configuration
+
+```toml
+# conduwuit-example.toml
+
+# Enable space permission cascading (power levels and role-based access).
+# When enabled, power levels cascade from Spaces to child rooms and rooms
+# can require roles for access. Applies to all Spaces on this server.
+# Default: false
+space_permission_cascading = false
+```
+
+## Custom State Events
+
+All events live in the Space room.
+
+### `m.space.roles` (state key: `""`)
+
+Defines the available roles for the Space. Two default roles (`admin` and `mod`)
+are created automatically when a Space is first encountered with the feature
+enabled.
+
+```json
+{
+  "roles": {
+    "admin": {
+      "description": "Space administrator",
+      "power_level": 100
+    },
+    "mod": {
+      "description": "Space moderator",
+      "power_level": 50
+    },
+    "nsfw": {
+      "description": "Access to NSFW content"
+    },
+    "vip": {
+      "description": "VIP member"
+    }
+  }
+}
+```
+
+- `description` (string, required): Human-readable description.
+- `power_level` (integer, optional): If present, users with this role receive
+  this power level in all child rooms. When a user holds multiple roles with
+  power levels, the highest value wins.
+
+### `m.space.role.member` (state key: user ID)
+
+Assigns roles to a user within the Space.
+
+```json
+{
+  "roles": ["nsfw", "vip"]
+}
+```
+
+### `m.space.role.room` (state key: room ID)
+
+Declares which roles a child room requires. A user must hold **all** listed
+roles to access the room.
+
+```json
+{
+  "required_roles": ["nsfw"]
+}
+```
+
+## Enforcement Rules
+
+All enforcement is skipped when `space_permission_cascading = false`.
+
+### 1. Join gating
+
+When a user attempts to join a room that is a direct child of a Space:
+
+- Look up the room's `m.space.role.room` event in the parent Space.
+- If the room has `required_roles`, check the user's `m.space.role.member`.
+- Reject the join if the user is missing any required role.
+
+### 2. Power level override
+
+For every user in a child room of a Space:
+
+- Look up their roles via `m.space.role.member` in the parent Space.
+- For each role that has a `power_level`, take the highest value.
+- Override the user's power level in the child room's `m.room.power_levels`.
+- Reject attempts to manually set per-room power levels that conflict with
+  Space-granted levels.
+
+### 3. Role revocation
+
+When an `m.space.role.member` event is updated and a role is removed:
+
+- Identify all child rooms that require the removed role.
+- Auto-kick the user from rooms they no longer qualify for.
+- Recalculate and update the user's power level in all child rooms.
+
+### 4. Room requirement change
+
+When an `m.space.role.room` event is updated with new requirements:
+
+- Check all current members of the room.
+- Auto-kick members who do not hold all newly required roles.
+
+### 5. Auto-join on role grant
+
+When an `m.space.role.member` event is updated and a role is added:
+
+- Find all child rooms where the user now meets all required roles.
+- Auto-join the user to qualifying rooms they are not already in.
+
+This also applies when a user first joins the Space — they are auto-joined to
+all child rooms they qualify for. Rooms with no role requirements auto-join all
+Space members.
+
+### 6. New child room
+
+When a new `m.space.child` event is added to a Space:
+
+- Auto-join all qualifying Space members to the new child room.
+
+## Caching & Indexing
+
+The source of truth is always the state events. The server maintains an
+in-memory index for fast enforcement lookups, following the same patterns as the
+existing `roomid_spacehierarchy_cache`.
+
+### Index structures
+
+| Index                        | Source event           |
+|------------------------------|------------------------|
+| Space → roles defined        | `m.space.roles`        |
+| Space → user → roles         | `m.space.role.member`  |
+| Space → room → required roles| `m.space.role.room`    |
+| Room → parent Space          | `m.space.child` (reverse lookup) |
+
+The Space → child rooms mapping already exists.
+
+### Cache invalidation triggers
+
+| Event changed              | Action                                              |
+|----------------------------|-----------------------------------------------------|
+| `m.space.roles`            | Refresh role definitions, revalidate all members    |
+| `m.space.role.member`      | Refresh user's roles, trigger auto-join/kick        |
+| `m.space.role.room`        | Refresh room requirements, trigger auto-join/kick   |
+| `m.space.child` added      | Index new child, auto-join qualifying members       |
+| `m.space.child` removed    | Remove from index (no auto-kick)                    |
+| Server startup             | Full rebuild from state events                      |
+
+## Admin Room Commands
+
+Roles are managed via the existing admin room interface, which sends the
+appropriate state events under the hood and triggers enforcement.
+
+```
+!admin space roles list <space>
+!admin space roles add <space> <role_name> [description] [power_level]
+!admin space roles remove <space> <role_name>
+!admin space roles assign <space> <user_id> <role_name>
+!admin space roles revoke <space> <user_id> <role_name>
+!admin space roles require <space> <room_id> <role_name>
+!admin space roles unrequire <space> <room_id> <role_name>
+!admin space roles user <space> <user_id>
+!admin space roles room <space> <room_id>
+```
+
+## Architecture
+
+**Approach:** Hybrid — state events for definition, database cache for
+enforcement.
+
+- State events are the source of truth and federate normally.
+- The server maintains an in-memory cache/index for fast enforcement.
+- Cache is invalidated on relevant state event changes and fully rebuilt on
+  startup.
+- All enforcement hooks (join gating, PL override, auto-join, auto-kick) check
+  the feature flag first and no-op when disabled.
+- Existing clients can manage roles via Developer Tools (custom state events).
+  The admin room commands provide a user-friendly interface.
+
+## Scope
+
+### In scope
+
+- Server-wide feature flag
+- Custom state events for role definition, assignment, and room requirements
+- Power level cascading (Space always wins)
+- Continuous enforcement (auto-join, auto-kick)
+- Admin room commands
+- In-memory caching with invalidation
+- Default `admin` (PL 100) and `mod` (PL 50) roles
+
+### Out of scope
+
+- Client-side UI for role management
+- Nested cascade through sub-spaces
+- Per-space opt-in/opt-out (it is server-wide)
+- Federation-specific logic beyond normal state event replication