···
1
+
# Governance PRD: Community Ownership & Moderation
3
+
**Status:** Planning / Not Started
4
+
**Owner:** Platform Team
5
+
**Last Updated:** 2025-10-10
9
+
Community governance defines who can manage communities, how moderation authority is distributed, and how communities can evolve ownership over time. This PRD outlines the authorization model for community management, from the initial simple role-based system to future decentralized governance.
11
+
The governance system must balance three competing needs:
12
+
1. **Community autonomy** - Communities should self-govern where possible
13
+
2. **Instance control** - Hosting instances need moderation/compliance powers
14
+
3. **User experience** - Clear, understandable permissions that work for self-hosted and centralized deployments
16
+
## Problem Statement
18
+
**Current State (2025-10-10):**
19
+
- Communities own their own atProto repositories (V2 architecture)
20
+
- Instance holds PDS credentials for infrastructure management
21
+
- No authorization model exists for who can update/manage communities
22
+
- Only implicit "owner" is the instance itself
25
+
1. **Self-hosted instances:** Instance operator can't delegate community management to trusted users
26
+
2. **Community lifecycle:** No way to transfer ownership or add co-managers
27
+
3. **Scaling moderation:** Single-owner model doesn't scale to large communities
28
+
4. **User expectations:** Forum users expect moderator teams, not single-admin models
31
+
- As a **self-hosted instance owner**, I want to create communities and assign moderators so I don't have to manage everything myself
32
+
- As a **community creator**, I want to add trusted moderators to help manage the community
33
+
- As a **moderator**, I want clear permissions on what I can/cannot do
34
+
- As an **instance admin**, I need emergency moderation powers for compliance/safety
36
+
## Architecture Evolution
38
+
### V1: Role-Based Authorization (Recommended Starting Point)
40
+
**Status:** Planned for initial implementation
43
+
Three-tier permission model with clear role hierarchy:
46
+
1. **Creator** - Original community founder (DID from `createdBy` field)
47
+
- Full control: update profile, manage moderators, delete community
48
+
- Can transfer creator role to another user
49
+
- Only one creator per community at a time
51
+
2. **Moderator** - Trusted community managers
52
+
- Can update community profile (name, description, avatar, banner)
53
+
- Can manage community content (posts, members)
54
+
- Cannot delete community or manage other moderators
55
+
- Multiple moderators allowed per community
57
+
3. **Instance Admin** - Infrastructure operator (implicit role)
58
+
- Emergency override for legal/safety compliance
59
+
- Can delist, quarantine, or remove communities
60
+
- Should NOT be used for day-to-day community management
61
+
- Authority derived from instance DID matching `hostedBy`
63
+
**Database Schema:**
65
+
community_moderators
66
+
- id (UUID, primary key)
67
+
- community_did (references communities.did)
68
+
- moderator_did (user DID)
69
+
- role (enum: 'creator', 'moderator')
70
+
- added_by (DID of user who granted role)
71
+
- added_at (timestamp)
72
+
- UNIQUE(community_did, moderator_did)
75
+
**Authorization Checks:**
76
+
- **Update community profile:** Creator OR Moderator
77
+
- **Add/remove moderators:** Creator only
78
+
- **Delete community:** Creator only
79
+
- **Transfer creator role:** Creator only
80
+
- **Instance moderation:** Instance admin only (emergency use)
82
+
**Implementation Approach:**
83
+
- Add `community_moderators` table to schema
84
+
- Create authorization middleware for XRPC endpoints
85
+
- Update service layer to check permissions before operations
86
+
- Store moderator list in both AppView DB and optionally in atProto repository
89
+
- ✅ Familiar to forum users (creator/moderator model is standard)
90
+
- ✅ Works for both centralized and self-hosted instances
91
+
- ✅ Clear separation of concerns (community vs instance authority)
92
+
- ✅ Easy to implement on top of existing V2 architecture
93
+
- ✅ Provides foundation for future governance features
96
+
- ❌ Still centralized (creator has ultimate authority)
97
+
- ❌ No democratic decision-making
98
+
- ❌ Moderator removal is unilateral (creator decision)
99
+
- ❌ No community input on governance changes
103
+
### V2: Moderator Tiers & Permissions
105
+
**Status:** Future enhancement (6-12 months)
108
+
Expand simple creator/moderator model with granular permissions:
110
+
**Permission Types:**
111
+
- `manage_profile` - Update name, description, images
112
+
- `manage_content` - Moderate posts, remove content
113
+
- `manage_members` - Ban users, manage reputation
114
+
- `manage_moderators` - Add/remove other moderators
115
+
- `manage_settings` - Change visibility, federation settings
116
+
- `delete_community` - Permanent deletion
118
+
**Moderator Tiers:**
119
+
- **Full Moderator:** All permissions except `delete_community`
120
+
- **Content Moderator:** Only `manage_content` and `manage_members`
121
+
- **Settings Moderator:** Only `manage_profile` and `manage_settings`
122
+
- **Custom:** Mix and match individual permissions
125
+
- Large communities with specialized mod teams
126
+
- Trial moderators with limited permissions
127
+
- Automated bots with narrow scopes (e.g., spam removal)
130
+
- More flexible but significantly more complex
131
+
- Harder to explain to users
132
+
- More surface area for authorization bugs
136
+
### V3: Democratic Governance (Future Vision)
138
+
**Status:** Long-term goal (12-24+ months)
141
+
Communities can opt into democratic decision-making for major actions:
143
+
**Governance Models:**
144
+
1. **Direct Democracy** - All members vote on proposals
145
+
2. **Representative** - Elected moderators serve fixed terms
146
+
3. **Sortition** - Random selection of moderators from active members (like jury duty)
147
+
4. **Hybrid** - Combination of elected + appointed moderators
149
+
**Votable Actions:**
150
+
- Adding/removing moderators
151
+
- Updating community rules/guidelines
152
+
- Changing visibility or federation settings
153
+
- Migrating to a different instance
154
+
- Transferring creator role
155
+
- Deleting/archiving the community
157
+
**Governance Configuration:**
158
+
- Stored in `social.coves.community.profile` under `governance` field
159
+
- Defines voting thresholds (e.g., 60% approval, 10% quorum)
160
+
- Sets voting windows (e.g., 7-day voting period)
161
+
- Specifies time locks (e.g., 3-day delay before execution)
163
+
**Implementation Considerations:**
164
+
- Requires on-chain or in-repository voting records for auditability
165
+
- Needs sybil-resistance (prevent fake accounts from voting)
166
+
- May require reputation/stake minimums to vote
167
+
- Should support delegation (I assign my vote to someone else)
169
+
**atProto Integration:**
170
+
- Votes could be stored as records in community repository
171
+
- Enables portable governance (votes migrate with community)
172
+
- Allows external tools to verify governance legitimacy
175
+
- ✅ True community ownership
176
+
- ✅ Democratic legitimacy for moderation decisions
177
+
- ✅ Resistant to moderator abuse/corruption
178
+
- ✅ Aligns with decentralization ethos
181
+
- ❌ Complex to implement correctly
182
+
- ❌ Voting participation often low in practice
183
+
- ❌ Vulnerable to brigading/vote manipulation
184
+
- ❌ Slower decision-making (may be unacceptable for urgent moderation)
185
+
- ❌ Legal/compliance issues (who's liable if community votes for illegal content?)
189
+
### V4: Multi-Tenant Ownership (Future Vision)
191
+
**Status:** Long-term goal (24+ months)
194
+
Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:
196
+
**Ownership Models:**
197
+
1. **Shared Custody** - Multiple DIDs hold credentials (multisig)
198
+
2. **Smart Contract Ownership** - On-chain DAO controls community
199
+
3. **Federated Ownership** - Distributed across multiple instances
200
+
4. **Delegated Ownership** - Community owned by a separate legal entity
203
+
- Large communities that span multiple instances
204
+
- Communities backed by organizations/companies
205
+
- Communities that need legal entity ownership
206
+
- Cross-platform communities (exists on multiple protocols)
208
+
**Technical Challenges:**
209
+
- Credential management with multiple owners (who holds PDS password?)
210
+
- Consensus on conflicting actions (one owner wants to delete, one doesn't)
211
+
- Migration complexity (transferring ownership stakes)
212
+
- Legal structure (who's liable, who pays hosting costs?)
216
+
## Implementation Roadmap
218
+
### Phase 1: V1 Role-Based System (Months 0-3)
221
+
- Ship basic creator/moderator authorization
222
+
- Enable self-hosted instances to delegate management
223
+
- Foundation for all future governance features
226
+
- [ ] Database schema: `community_moderators` table
227
+
- [ ] Repository layer: CRUD for moderator records
228
+
- [ ] Service layer: Authorization checks for all operations
229
+
- [ ] XRPC endpoints:
230
+
- [ ] `social.coves.community.addModerator`
231
+
- [ ] `social.coves.community.removeModerator`
232
+
- [ ] `social.coves.community.listModerators`
233
+
- [ ] `social.coves.community.transferOwnership`
234
+
- [ ] Middleware: Role-based authorization for existing endpoints
235
+
- [ ] Tests: Integration tests for all permission scenarios
236
+
- [ ] Documentation: API docs, governance guide for instance admins
238
+
**Success Criteria:**
239
+
- Community creators can add/remove moderators
240
+
- Moderators can update community profile but not delete
241
+
- Authorization prevents unauthorized operations
242
+
- Works seamlessly for both centralized and self-hosted instances
246
+
### Phase 2: Moderator Permissions & Tiers (Months 3-6)
249
+
- Add granular permission system
250
+
- Support larger communities with specialized mod teams
253
+
- [ ] Schema: Add `permissions` JSON column to `community_moderators`
254
+
- [ ] Permission framework: Define and validate permission sets
255
+
- [ ] XRPC endpoints:
256
+
- [ ] `social.coves.community.updateModeratorPermissions`
257
+
- [ ] `social.coves.community.getModeratorPermissions`
258
+
- [ ] UI-friendly permission presets (Full Mod, Content Mod, etc.)
259
+
- [ ] Audit logging: Track permission changes and usage
261
+
**Success Criteria:**
262
+
- Communities can create custom moderator roles
263
+
- Permission checks prevent unauthorized operations
264
+
- Clear audit trail of who did what with which permissions
268
+
### Phase 3: Democratic Governance (Months 6-18)
271
+
- Enable opt-in democratic decision-making
272
+
- Support voting on moderators and major community changes
275
+
- [ ] Governance framework: Define votable actions and thresholds
276
+
- [ ] Voting system: Proposal creation, voting, execution
277
+
- [ ] Sybil resistance: Require minimum reputation/activity to vote
278
+
- [ ] Lexicon: `social.coves.community.proposal` and `social.coves.community.vote`
279
+
- [ ] XRPC endpoints:
280
+
- [ ] `social.coves.community.createProposal`
281
+
- [ ] `social.coves.community.vote`
282
+
- [ ] `social.coves.community.executeProposal`
283
+
- [ ] `social.coves.community.listProposals`
284
+
- [ ] Time locks and voting windows
285
+
- [ ] Delegation system (optional)
287
+
**Success Criteria:**
288
+
- Communities can opt into democratic governance
289
+
- Proposals can be created, voted on, and executed
290
+
- Voting records are portable (stored in repository)
291
+
- System prevents vote manipulation
295
+
### Phase 4: Multi-Tenant Ownership (Months 18+)
298
+
- Research and prototype shared ownership models
299
+
- Enable communities backed by organizations/DAOs
302
+
- [ ] Research: Survey existing DAO/multisig solutions
303
+
- [ ] Prototype: Multisig credential management
304
+
- [ ] Legal review: Liability and compliance considerations
305
+
- [ ] Integration: Bridge to existing DAO platforms (if applicable)
307
+
**Success Criteria:**
308
+
- Proof of concept for shared ownership
309
+
- Clear legal framework for multi-tenant communities
310
+
- Migration path from single-owner to multi-owner
316
+
### Phase 1 (V1) Questions
317
+
1. **Moderator limit:** Should there be a maximum number of moderators per community?
318
+
- **Recommendation:** Start with soft limit (e.g., 25), raise if needed
320
+
2. **Moderator-added moderators:** Can moderators add other moderators, or only the creator?
321
+
- **Recommendation:** Creator-only to start (simpler), add in Phase 2 if needed
323
+
3. **Moderator storage:** Store moderator list in atProto repository or just AppView DB?
324
+
- **Recommendation:** AppView DB initially (faster), add repository sync in Phase 2 for portability
326
+
4. **Creator transfer:** How to prevent accidental ownership transfers?
327
+
- **Recommendation:** Require confirmation from new creator before transfer completes
329
+
5. **Inactive creators:** How to handle communities where creator is gone/inactive?
330
+
- **Recommendation:** Instance admin emergency transfer after X months inactivity (define in Phase 2)
332
+
### Phase 2 (V2) Questions
333
+
1. **Permission inheritance:** Do higher roles automatically include lower role permissions?
334
+
- Research standard forum software patterns
336
+
2. **Permission UI:** How to make granular permissions understandable to non-technical users?
337
+
- Consider permission "bundles" or presets
339
+
3. **Permission changes:** Can creator retroactively change moderator permissions?
340
+
- Should probably require confirmation/re-acceptance from moderator
342
+
### Phase 3 (V3) Questions
343
+
1. **Voter eligibility:** What constitutes "membership" for voting purposes?
344
+
- Active posters? Subscribers? Time-based (member for X days)?
346
+
2. **Vote privacy:** Should votes be public or private?
347
+
- Public = transparent, but risk of social pressure
348
+
- Private = freedom, but harder to audit
350
+
3. **Emergency override:** Can instance still moderate if community votes for illegal content?
351
+
- Yes (instance liability), but how to make this clear and minimize abuse?
353
+
4. **Governance defaults:** What happens to communities that don't explicitly configure governance?
354
+
- Fall back to V1 creator/moderator model
356
+
### Phase 4 (V4) Questions
357
+
1. **Credential custody:** Who physically holds the PDS credentials in multi-tenant scenario?
358
+
- Multisig wallet? Threshold encryption? Trusted third party?
360
+
2. **Cost sharing:** How to split hosting costs across multiple owners?
361
+
- Smart contract? Legal entity? Manual coordination?
363
+
3. **Conflict resolution:** What happens when co-owners disagree?
364
+
- Voting thresholds? Arbitration? Fork the community?
370
+
### V1 Launch Metrics
371
+
- [ ] 90%+ of self-hosted instances create at least one community
372
+
- [ ] Average 2+ moderators per active community
373
+
- [ ] Zero authorization bypass bugs in production
374
+
- [ ] Creator → Moderator permission model understandable to users (< 5% support tickets about roles)
376
+
### V2 Adoption Metrics
377
+
- [ ] 20%+ of communities use custom permission sets
378
+
- [ ] Zero permission escalation vulnerabilities
379
+
- [ ] Audit logs successfully resolve 90%+ of disputes
381
+
### V3 Governance Metrics
382
+
- [ ] 10%+ of communities opt into democratic governance
383
+
- [ ] Average voter turnout > 20% for major decisions
384
+
- [ ] < 5% of votes successfully manipulated/brigaded
385
+
- [ ] Community satisfaction with governance process > 70%
389
+
## Technical Decisions Log
391
+
### 2025-10-10: V1 Role-Based Model Selected
392
+
**Decision:** Start with simple creator/moderator two-tier system
395
+
- Familiar to users (matches existing forum software)
396
+
- Simple to implement on top of V2 architecture
397
+
- Works for both centralized and self-hosted instances
398
+
- Provides clear migration path to democratic governance
399
+
- Avoids over-engineering before we understand actual usage patterns
401
+
**Alternatives Considered:**
402
+
- **atProto delegation:** More protocol-native, but spec is immature
403
+
- **Multisig from day one:** Too complex, unclear user demand
404
+
- **Single creator only:** Too limited for real-world use
406
+
**Trade-offs Accepted:**
407
+
- Won't support democratic governance initially
408
+
- Creator still has ultimate authority (not truly decentralized)
409
+
- Moderator permissions are coarse-grained
415
+
- [PRD_COMMUNITIES.md](PRD_COMMUNITIES.md) - Core community architecture and V2 implementation
416
+
- PRD_MODERATION.md (TODO) - Content moderation, reporting, labeling
417
+
- PRD_FEDERATION.md (TODO) - Cross-instance community discovery and moderation
423
+
- atProto Authorization Spec: https://atproto.com/specs/xrpc#authentication
424
+
- Bluesky Moderation System: https://docs.bsky.app/docs/advanced-guides/moderation
425
+
- Reddit Moderator System: https://mods.reddithelp.com/hc/en-us/articles/360009381491
426
+
- Discord Permission System: https://discord.com/developers/docs/topics/permissions
427
+
- DAO Governance Patterns: https://ethereum.org/en/dao/
bretton.dev