A community based topic aggregation platform built on atproto
bretton.dev
1# Governance PRD: Community Ownership & Moderation
2
3**Status:** Planning / Not Started
4**Owner:** Platform Team
5**Last Updated:** 2025-10-10
6
7## Overview
8
9Community 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.
10
11The governance system must balance three competing needs:
121. **Community autonomy** - Communities should self-govern where possible
132. **Instance control** - Hosting instances need moderation/compliance powers
143. **User experience** - Clear, understandable permissions that work for self-hosted and centralized deployments
15
16## Problem Statement
17
18**Current State (2025-10-15):**
19- Communities own their own atProto repositories (V2 architecture)
20- Instance holds PDS credentials for infrastructure management
21- Basic authorization exists: only `createdBy` user can update communities
22- No moderator management system exists yet
23
24**Note:** Moderator management and advanced governance are **post-alpha** (Beta Phase 1) work. Alpha focuses on basic community CRUD operations.
25
26**Key Issues:**
271. **Self-hosted instances:** Instance operator can't delegate community management to trusted users
282. **Community lifecycle:** No way to transfer ownership or add co-managers
293. **Scaling moderation:** Single-owner model doesn't scale to large communities
304. **User expectations:** Forum users expect moderator teams, not single-admin models
31
32**User Stories:**
33- As a **self-hosted instance owner**, I want to create communities and assign moderators so I don't have to manage everything myself
34- As a **community creator**, I want to add trusted moderators to help manage the community
35- As a **moderator**, I want clear permissions on what I can/cannot do
36- As an **instance admin**, I need emergency moderation powers for compliance/safety
37
38## Architecture Evolution
39
40### V1: Role-Based Authorization (Recommended Starting Point)
41
42**Status:** Planned for initial implementation
43
44**Core Concept:**
45Three-tier permission model with clear role hierarchy:
46
47**Roles:**
481. **Creator** - Original community founder (DID from `createdBy` field)
49 - Full control: update profile, manage moderators, delete community
50 - Can transfer creator role to another user
51 - Only one creator per community at a time
52
532. **Moderator** - Trusted community managers
54 - Can update community profile (name, description, avatar, banner)
55 - Can manage community content (posts, members)
56 - Cannot delete community or manage other moderators
57 - Multiple moderators allowed per community
58
593. **Instance Admin** - Infrastructure operator (implicit role)
60 - Emergency override for legal/safety compliance
61 - Can delist, quarantine, or remove communities
62 - Should NOT be used for day-to-day community management
63 - Authority derived from instance DID matching `hostedBy`
64
65**Database Schema:**
66```
67community_moderators
68- id (UUID, primary key)
69- community_did (references communities.did)
70- moderator_did (user DID)
71- role (enum: 'creator', 'moderator')
72- added_by (DID of user who granted role)
73- added_at (timestamp)
74- UNIQUE(community_did, moderator_did)
75```
76
77**Authorization Checks:**
78- **Update community profile:** Creator OR Moderator
79- **Add/remove moderators:** Creator only
80- **Delete community:** Creator only
81- **Transfer creator role:** Creator only
82- **Instance moderation:** Instance admin only (emergency use)
83
84**Implementation Approach:**
85- Add `community_moderators` table to schema
86- Create authorization middleware for XRPC endpoints
87- Update service layer to check permissions before operations
88- Store moderator list in both AppView DB and optionally in atProto repository
89
90**Benefits:**
91- ✅ Familiar to forum users (creator/moderator model is standard)
92- ✅ Works for both centralized and self-hosted instances
93- ✅ Clear separation of concerns (community vs instance authority)
94- ✅ Easy to implement on top of existing V2 architecture
95- ✅ Provides foundation for future governance features
96
97**Limitations:**
98- ❌ Still centralized (creator has ultimate authority)
99- ❌ No democratic decision-making
100- ❌ Moderator removal is unilateral (creator decision)
101- ❌ No community input on governance changes
102
103---
104
105### V2: Moderator Tiers & Permissions
106
107**Status:** Future enhancement (6-12 months)
108
109**Concept:**
110Expand simple creator/moderator model with granular permissions:
111
112**Permission Types:**
113- `manage_profile` - Update name, description, images
114- `manage_content` - Moderate posts, remove content
115- `manage_members` - Ban users, manage reputation
116- `manage_moderators` - Add/remove other moderators
117- `manage_settings` - Change visibility, federation settings
118- `delete_community` - Permanent deletion
119
120**Moderator Tiers:**
121- **Full Moderator:** All permissions except `delete_community`
122- **Content Moderator:** Only `manage_content` and `manage_members`
123- **Settings Moderator:** Only `manage_profile` and `manage_settings`
124- **Custom:** Mix and match individual permissions
125
126**Use Cases:**
127- Large communities with specialized mod teams
128- Trial moderators with limited permissions
129- Automated bots with narrow scopes (e.g., spam removal)
130
131**Trade-offs:**
132- More flexible but significantly more complex
133- Harder to explain to users
134- More surface area for authorization bugs
135
136---
137
138### V3: Democratic Governance (Future Vision)
139
140**Status:** Long-term goal (12-24+ months)
141
142**Concept:**
143Communities can opt into democratic decision-making for major actions:
144
145**Governance Models:**
1461. **Direct Democracy** - All members vote on proposals
1472. **Representative** - Elected moderators serve fixed terms
1483. **Sortition** - Random selection of moderators from active members (like jury duty)
1494. **Hybrid** - Combination of elected + appointed moderators
150
151**Votable Actions:**
152- Adding/removing moderators
153- Updating community rules/guidelines
154- Changing visibility or federation settings
155- Migrating to a different instance
156- Transferring creator role
157- Deleting/archiving the community
158
159**Governance Configuration:**
160- Stored in `social.coves.community.profile` under `governance` field
161- Defines voting thresholds (e.g., 60% approval, 10% quorum)
162- Sets voting windows (e.g., 7-day voting period)
163- Specifies time locks (e.g., 3-day delay before execution)
164
165**Implementation Considerations:**
166- Requires on-chain or in-repository voting records for auditability
167- Needs sybil-resistance (prevent fake accounts from voting)
168- May require reputation/stake minimums to vote
169- Should support delegation (I assign my vote to someone else)
170
171**atProto Integration:**
172- Votes could be stored as records in community repository
173- Enables portable governance (votes migrate with community)
174- Allows external tools to verify governance legitimacy
175
176**Benefits:**
177- ✅ True community ownership
178- ✅ Democratic legitimacy for moderation decisions
179- ✅ Resistant to moderator abuse/corruption
180- ✅ Aligns with decentralization ethos
181
182**Challenges:**
183- ❌ Complex to implement correctly
184- ❌ Voting participation often low in practice
185- ❌ Vulnerable to brigading/vote manipulation
186- ❌ Slower decision-making (may be unacceptable for urgent moderation)
187- ❌ Legal/compliance issues (who's liable if community votes for illegal content?)
188
189---
190
191### V4: Multi-Tenant Ownership (Future Vision)
192
193**Status:** Long-term goal (24+ months)
194
195**Concept:**
196Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:
197
198**Ownership Models:**
1991. **Shared Custody** - Multiple DIDs hold credentials (multisig)
2002. **Smart Contract Ownership** - On-chain DAO controls community
2013. **Federated Ownership** - Distributed across multiple instances
2024. **Delegated Ownership** - Community owned by a separate legal entity
203
204**Use Cases:**
205- Large communities that span multiple instances
206- Communities backed by organizations/companies
207- Communities that need legal entity ownership
208- Cross-platform communities (exists on multiple protocols)
209
210**Technical Challenges:**
211- Credential management with multiple owners (who holds PDS password?)
212- Consensus on conflicting actions (one owner wants to delete, one doesn't)
213- Migration complexity (transferring ownership stakes)
214- Legal structure (who's liable, who pays hosting costs?)
215
216---
217
218## Implementation Roadmap
219
220### Phase 1: V1 Role-Based System (Months 0-3)
221
222**Goals:**
223- Ship basic creator/moderator authorization
224- Enable self-hosted instances to delegate management
225- Foundation for all future governance features
226
227**Deliverables:**
228- [ ] Database schema: `community_moderators` table
229- [ ] Repository layer: CRUD for moderator records
230- [ ] Service layer: Authorization checks for all operations
231- [ ] XRPC endpoints:
232 - [ ] `social.coves.community.addModerator`
233 - [ ] `social.coves.community.removeModerator`
234 - [ ] `social.coves.community.listModerators`
235 - [ ] `social.coves.community.transferOwnership`
236- [ ] Middleware: Role-based authorization for existing endpoints
237- [ ] Tests: Integration tests for all permission scenarios
238- [ ] Documentation: API docs, governance guide for instance admins
239
240**Success Criteria:**
241- Community creators can add/remove moderators
242- Moderators can update community profile but not delete
243- Authorization prevents unauthorized operations
244- Works seamlessly for both centralized and self-hosted instances
245
246---
247
248### Phase 2: Moderator Permissions & Tiers (Months 3-6)
249
250**Goals:**
251- Add granular permission system
252- Support larger communities with specialized mod teams
253
254**Deliverables:**
255- [ ] Schema: Add `permissions` JSON column to `community_moderators`
256- [ ] Permission framework: Define and validate permission sets
257- [ ] XRPC endpoints:
258 - [ ] `social.coves.community.updateModeratorPermissions`
259 - [ ] `social.coves.community.getModeratorPermissions`
260- [ ] UI-friendly permission presets (Full Mod, Content Mod, etc.)
261- [ ] Audit logging: Track permission changes and usage
262
263**Success Criteria:**
264- Communities can create custom moderator roles
265- Permission checks prevent unauthorized operations
266- Clear audit trail of who did what with which permissions
267
268---
269
270### Phase 3: Democratic Governance (Months 6-18)
271
272**Goals:**
273- Enable opt-in democratic decision-making
274- Support voting on moderators and major community changes
275
276**Deliverables:**
277- [ ] Governance framework: Define votable actions and thresholds
278- [ ] Voting system: Proposal creation, voting, execution
279- [ ] Sybil resistance: Require minimum reputation/activity to vote
280- [ ] Lexicon: `social.coves.community.proposal` and `social.coves.community.vote`
281- [ ] XRPC endpoints:
282 - [ ] `social.coves.community.createProposal`
283 - [ ] `social.coves.community.vote`
284 - [ ] `social.coves.community.executeProposal`
285 - [ ] `social.coves.community.listProposals`
286- [ ] Time locks and voting windows
287- [ ] Delegation system (optional)
288
289**Success Criteria:**
290- Communities can opt into democratic governance
291- Proposals can be created, voted on, and executed
292- Voting records are portable (stored in repository)
293- System prevents vote manipulation
294
295---
296
297### Phase 4: Multi-Tenant Ownership (Months 18+)
298
299**Goals:**
300- Research and prototype shared ownership models
301- Enable communities backed by organizations/DAOs
302
303**Deliverables:**
304- [ ] Research: Survey existing DAO/multisig solutions
305- [ ] Prototype: Multisig credential management
306- [ ] Legal review: Liability and compliance considerations
307- [ ] Integration: Bridge to existing DAO platforms (if applicable)
308
309**Success Criteria:**
310- Proof of concept for shared ownership
311- Clear legal framework for multi-tenant communities
312- Migration path from single-owner to multi-owner
313
314---
315
316## Open Questions
317
318### Phase 1 (V1) Questions
3191. **Moderator limit:** Should there be a maximum number of moderators per community?
320 - **Recommendation:** Start with soft limit (e.g., 25), raise if needed
321
3222. **Moderator-added moderators:** Can moderators add other moderators, or only the creator?
323 - **Recommendation:** Creator-only to start (simpler), add in Phase 2 if needed
324
3253. **Moderator storage:** Store moderator list in atProto repository or just AppView DB?
326 - **Recommendation:** AppView DB initially (faster), add repository sync in Phase 2 for portability
327
3284. **Creator transfer:** How to prevent accidental ownership transfers?
329 - **Recommendation:** Require confirmation from new creator before transfer completes
330
3315. **Inactive creators:** How to handle communities where creator is gone/inactive?
332 - **Recommendation:** Instance admin emergency transfer after X months inactivity (define in Phase 2)
333
334### Phase 2 (V2) Questions
3351. **Permission inheritance:** Do higher roles automatically include lower role permissions?
336 - Research standard forum software patterns
337
3382. **Permission UI:** How to make granular permissions understandable to non-technical users?
339 - Consider permission "bundles" or presets
340
3413. **Permission changes:** Can creator retroactively change moderator permissions?
342 - Should probably require confirmation/re-acceptance from moderator
343
344### Phase 3 (V3) Questions
3451. **Voter eligibility:** What constitutes "membership" for voting purposes?
346 - Active posters? Subscribers? Time-based (member for X days)?
347
3482. **Vote privacy:** Should votes be public or private?
349 - Public = transparent, but risk of social pressure
350 - Private = freedom, but harder to audit
351
3523. **Emergency override:** Can instance still moderate if community votes for illegal content?
353 - Yes (instance liability), but how to make this clear and minimize abuse?
354
3554. **Governance defaults:** What happens to communities that don't explicitly configure governance?
356 - Fall back to V1 creator/moderator model
357
358### Phase 4 (V4) Questions
3591. **Credential custody:** Who physically holds the PDS credentials in multi-tenant scenario?
360 - Multisig wallet? Threshold encryption? Trusted third party?
361
3622. **Cost sharing:** How to split hosting costs across multiple owners?
363 - Smart contract? Legal entity? Manual coordination?
364
3653. **Conflict resolution:** What happens when co-owners disagree?
366 - Voting thresholds? Arbitration? Fork the community?
367
368---
369
370## Success Metrics
371
372### V1 Launch Metrics
373- [ ] 90%+ of self-hosted instances create at least one community
374- [ ] Average 2+ moderators per active community
375- [ ] Zero authorization bypass bugs in production
376- [ ] Creator → Moderator permission model understandable to users (< 5% support tickets about roles)
377
378### V2 Adoption Metrics
379- [ ] 20%+ of communities use custom permission sets
380- [ ] Zero permission escalation vulnerabilities
381- [ ] Audit logs successfully resolve 90%+ of disputes
382
383### V3 Governance Metrics
384- [ ] 10%+ of communities opt into democratic governance
385- [ ] Average voter turnout > 20% for major decisions
386- [ ] < 5% of votes successfully manipulated/brigaded
387- [ ] Community satisfaction with governance process > 70%
388
389---
390
391## Technical Decisions Log
392
393### 2025-10-11: Moderator Records Storage Location
394**Decision:** Store moderator records in community's repository (`at://community_did/social.coves.community.moderator/{tid}`), not user's repository
395
396**Rationale:**
3971. **Federation security**: Community's PDS can write/delete records in its own repo without cross-PDS coordination
3982. **Attack resistance**: Malicious self-hosted instances cannot forge or retain moderator status after revocation
3993. **Single source of truth**: Community's repo is authoritative; no need to check multiple repos + revocation lists
4004. **Instant revocation**: Deleting the record immediately removes moderator status across all instances
4015. **Simpler implementation**: No invitation flow, no multi-step acceptance, no revocation reconciliation
402
403**Security Analysis:**
404- **Option B (user's repo) vulnerability**: Attacker could self-host malicious AppView that ignores revocation signals stored in community's AppView database, presenting their moderator record as "proof" of authority
405- **Option A (community's repo) security**: Even malicious instances must query community's PDS for authoritative moderator list; attacker cannot forge records in community's repository
406
407**Alternatives Considered:**
408- **User's repo**: Follows atProto pattern for relationships (like `app.bsky.graph.follow`), provides user consent model, but introduces cross-instance write complexity and security vulnerabilities
409- **Hybrid (both repos)**: Assignment in community's repo + acceptance in user's repo provides consent without compromising security, but significantly increases complexity
410
411**Trade-offs Accepted:**
412- No explicit user consent (moderators are appointed, not invited)
413- Users cannot easily query "what do I moderate?" without AppView index
414- Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)
415
416**Implementation Notes:**
417- Moderator records are source of truth for permissions
418- AppView indexes these records from firehose for efficient querying
419- User consent can be added later via optional acceptance records without changing security model
420- Matches Bluesky's pattern: relationships in user's repo, service configuration in service's repo
421
422---
423
424### 2025-10-10: V1 Role-Based Model Selected
425**Decision:** Start with simple creator/moderator two-tier system
426
427**Rationale:**
428- Familiar to users (matches existing forum software)
429- Simple to implement on top of V2 architecture
430- Works for both centralized and self-hosted instances
431- Provides clear migration path to democratic governance
432- Avoids over-engineering before we understand actual usage patterns
433
434**Alternatives Considered:**
435- **atProto delegation:** More protocol-native, but spec is immature
436- **Multisig from day one:** Too complex, unclear user demand
437- **Single creator only:** Too limited for real-world use
438
439**Trade-offs Accepted:**
440- Won't support democratic governance initially
441- Creator still has ultimate authority (not truly decentralized)
442- Moderator permissions are coarse-grained
443
444---
445
446## Related PRDs
447
448- [PRD_COMMUNITIES.md](PRD_COMMUNITIES.md) - Core community architecture and V2 implementation
449- PRD_MODERATION.md (TODO) - Content moderation, reporting, labeling
450- PRD_FEDERATION.md (TODO) - Cross-instance community discovery and moderation
451
452---
453
454## References
455
456- atProto Authorization Spec: https://atproto.com/specs/xrpc#authentication
457- Bluesky Moderation System: https://docs.bsky.app/docs/advanced-guides/moderation
458- Reddit Moderator System: https://mods.reddithelp.com/hc/en-us/articles/360009381491
459- Discord Permission System: https://discord.com/developers/docs/topics/permissions
460- DAO Governance Patterns: https://ethereum.org/en/dao/