Rooms, Permissions, and Preferences

Two Role Layers

SyncTV has two role layers. Keep them separate.

Layer	Roles	Scope
Global user role	`root`, `admin`, `user`	Platform administration, user management, room management, system settings
Room role	`creator`, `admin`, `member`, `guest`	Playback, members, media, chat, and settings inside one room

A global admin is not automatically a room admin. A room admin is not a platform administrator.

Global User Roles

Role	Boundary
`root`	Super administrator; can manage root/admin/user accounts, global settings, and all rooms
`admin`	Platform administrator; can manage normal users and rooms, but cannot modify root or equally privileged admins
`user`	Normal user; uses rooms and media features according to business permissions

User status is derived from ban records:

Status	Effect
`active`	Can log in, create rooms, and join rooms
`banned`	Cannot log in, create rooms, or join rooms

Room Roles

Room role	Default meaning
`creator`	Room creator; has all room permissions and cannot be weakened by room settings
`admin`	Room administrator; can manage members, playback, media, room settings, and moderation by default
`member`	Normal member; can chat, add/edit/delete own media, and view playlist/member/chat data by default
`guest`	Read-only guest; can view playlist by default

Room roles provide base permissions. Room settings and member overrides then add or remove permissions.

Permission Evaluation

Effective permissions are evaluated in three layers:

global role default permissions
  -> room settings added/removed permissions
  -> member-specific added/removed permissions

Rules:

creator always has all room permissions.
Add is applied before remove. If the same bit is both added and removed, remove wins.
member_added_permissions cannot exceed the admin-level ceiling.
guest_added_permissions cannot exceed the member-level ceiling.
DELETE_ROOM is not a room-delegable permission. Room deletion belongs to the creator or the platform management plane.

Major Permission Bits

Permission	Meaning
`SEND_CHAT`	Send chat and danmaku messages
`ADD_MEDIA`	Add media
`DELETE_MEDIA_SELF` / `DELETE_MEDIA_ANY`	Delete own media / delete any media
`EDIT_MEDIA_SELF` / `EDIT_MEDIA_ANY`	Edit own media / edit any media
`REORDER_PLAYLIST`	Reorder playlist
`CLEAR_PLAYLIST`	Clear playlist
`START_LIVE`	Start livestream publishing
`PLAY_CONTROL`	Play, pause, and seek
`CHANGE_CURRENT_MEDIA`	Switch current media
`CHANGE_PLAYBACK_RATE`	Change playback speed
`APPROVE_MEMBER`	Approve or reject join requests
`KICK_MEMBER`	Kick members
`BAN_MEMBER`	Ban or unban members
`SET_MEMBER_PERMISSIONS`	Change member permissions
`ADD_MEMBER`	Add members directly
`SET_ROOM_SETTINGS`	Modify room settings
`DELETE_CHAT`	Delete chat messages
`DELETE_ROOM`	Delete room; not a normal room-delegable permission
`VIEW_PLAYLIST`	View playlist
`VIEW_MEMBER_LIST`	View member list
`VIEW_CHAT_HISTORY`	View chat history
`USE_WEBRTC`	Use WebRTC voice/video features

Permission values are usually represented as u64 bitmasks in APIs and CLI commands. Before changing a bitmask, confirm target role and current effective permissions.

Room Settings

Room settings control join policy, room features, and default permissions.

Setting	Default	Meaning
`require_password`	`false`	Require room password
`allow_guest_join`	`false`	Allow guests to join
`max_members`	`100`	Maximum members; upper bound `10000`
`require_approval`	`false`	Require join approval
`allow_auto_join`	`true`	Allow eligible users to auto-join
`chat_enabled`	`true`	Enable chat
`danmaku_enabled`	`true`	Enable danmaku
`auto_play`	`{}`	Auto-play policy JSON
`admin_added_permissions` / `admin_removed_permissions`	`0`	Admin default permission changes
`member_added_permissions` / `member_removed_permissions`	`0`	Member default permission changes
`guest_added_permissions` / `guest_removed_permissions`	`0`	Guest default permission changes

Example:

synctv room settings get <ROOM_ID>
synctv room settings update <ROOM_ID> --settings-json '{"require_approval":true}'

Member Overrides

Member overrides are for exceptions, such as muting one member, granting playback control to one member, or removing ban capability from one administrator.

Semantics:

Base permissions come from the room role.
added_permissions adds normal member permissions.
removed_permissions removes normal member permissions.
Administrators can also have admin_added_permissions and admin_removed_permissions.
Weakening creator permissions has no effect.

Guidance:

Use roles for long-term permission design and member overrides for exceptions.
Too many overrides make troubleshooting harder; clean up stale overrides.
When removing administrator privileges, consider changing the role instead of stacking many deny bits.

User Preferences

User preferences are database-backed user-level settings, not YAML configuration.

Field	Default	Meaning
`two_factor_enabled`	`false`	User-level 2FA
`notifications.room_invitation_in_app`	`true`	In-app room invitation notifications
`notifications.room_event_in_app`	`true`	In-app room event notifications
`notifications.system_announcement_in_app`	`true`	In-app system announcements
`notifications.room_invitation_email`	`false`	Email room invitation notifications
`notifications.room_event_email`	`false`	Email room event notifications
`notifications.system_announcement_email`	`true`	Email system announcements
`provider_defaults.alist_instance_name`	`null`	Default Alist instance
`provider_defaults.emby_instance_name`	`null`	Default Emby instance
`provider_defaults.bilibili_instance_name`	`null`	Default Bilibili instance

The database table also has a settings JSONB extension payload for low-priority experimental preferences. Stable product preferences should use explicit columns. Do not store secrets, tokens, cookies, passwords, or provider credentials in it.

2FA constraints:

Enabling 2FA requires at least two local methods: password, WebAuthn/passkey, verified email.
OAuth2 is not counted as a local 2FA factor, but 2FA-enabled users may log in with OAuth2.
Removing an authentication method while 2FA is enabled must still leave at least two usable local methods.

Administration Strategy

Avoid Raw Bitmasks

Prefer roles over direct bitmask edits. If a bitmask change is necessary, record the current value and reason.

Separate Scopes

Platform admin and room admin are separate concepts. Diagnose permission issues by layer first.

Preferences Are Runtime Data

User preferences are changed through API/CLI and should not live in YAML or Helm values.

Verify Behavior

After changing join rules, permissions, or 2FA, test real login, room join, and playback flows.