427e7578-d7bf-49c8-aee9-2dd999e25316/specs/archived/006-role-permission-system/README.md

status, created, tags, priority, created_at, depends_on, updated_at, transitions

status	created	tags	priority	created_at	depends_on	updated_at	transitions
archived	2026-03-16	auth roles	high	2026-03-16T07:51:49.636Z	004-poll-data-model	2026-03-16T09:18:35.900Z	status at archived 2026-03-16T09:18:35.900Z

Role & Permission System

Status: 📦 Archived · Priority: High · Created: 2026-03-16 · Tags: auth, roles

Overview

Each poll has a role-based permission system. The owner assigns roles to users they discover or invite. Roles control what actions a user can perform on a poll.

Design

Roles & Permissions

Action	Viewer	Participant	Moderator	Owner
View poll & results	✅	✅	✅	✅
Add options	❌	✅	✅	✅
Vote	❌	✅	✅	✅
Add/remove users	❌	❌	✅	✅
Start/stop poll	❌	❌	✅	✅
Delete poll	❌	❌	❌	✅

Implementation

• Owner is implicit (poll.ownerId === userId)
• Roles stored in poll.roles[] array
• Role changes are broadcast to all connected peers
• Moderators can invite users by peer ID (discovered via spec 007) or by sharing a poll link
• Permission checks happen both client-side (UI) and on message receipt (owner validates)

Invite Flow

1. Owner/moderator discovers a user (see spec 007) or has their peer ID
2. Assigns them a role → updates poll.roles[]
3. When that user connects, they receive the poll state including their role
4. Users without a role who connect via link get viewer by default

Plan

• Implement role assignment data model
• Create permission check utility (canVote(), canModerate(), etc.)
• Build user management UI in poll detail page
• Implement role change broadcast over PeerJS
• Owner-side validation of incoming messages against roles

Test

• Viewer cannot vote or add options
• Participant can vote and add options
• Moderator can add/remove users and start/stop poll
• Only owner can delete
• Unknown users connecting via link get viewer role