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-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
23
24**Key Issues:**
251. **Self-hosted instances:** Instance operator can't delegate community management to trusted users
262. **Community lifecycle:** No way to transfer ownership or add co-managers
273. **Scaling moderation:** Single-owner model doesn't scale to large communities
284. **User expectations:** Forum users expect moderator teams, not single-admin models
29
30**User Stories:**
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
35
36## Architecture Evolution
37
38### V1: Role-Based Authorization (Recommended Starting Point)
39
40**Status:** Planned for initial implementation
41
42**Core Concept:**
43Three-tier permission model with clear role hierarchy:
44
45**Roles:**
461. **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
50
512. **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
56
573. **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`
62
63**Database Schema:**
64```
65community_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)
73```
74
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)
81
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
87
88**Benefits:**
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
94
95**Limitations:**
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
100
101---
102
103### V2: Moderator Tiers & Permissions
104
105**Status:** Future enhancement (6-12 months)
106
107**Concept:**
108Expand simple creator/moderator model with granular permissions:
109
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
117
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
123
124**Use Cases:**
125- Large communities with specialized mod teams
126- Trial moderators with limited permissions
127- Automated bots with narrow scopes (e.g., spam removal)
128
129**Trade-offs:**
130- More flexible but significantly more complex
131- Harder to explain to users
132- More surface area for authorization bugs
133
134---
135
136### V3: Democratic Governance (Future Vision)
137
138**Status:** Long-term goal (12-24+ months)
139
140**Concept:**
141Communities can opt into democratic decision-making for major actions:
142
143**Governance Models:**
1441. **Direct Democracy** - All members vote on proposals
1452. **Representative** - Elected moderators serve fixed terms
1463. **Sortition** - Random selection of moderators from active members (like jury duty)
1474. **Hybrid** - Combination of elected + appointed moderators
148
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
156
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)
162
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)
168
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
173
174**Benefits:**
175- ✅ True community ownership
176- ✅ Democratic legitimacy for moderation decisions
177- ✅ Resistant to moderator abuse/corruption
178- ✅ Aligns with decentralization ethos
179
180**Challenges:**
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?)
186
187---
188
189### V4: Multi-Tenant Ownership (Future Vision)
190
191**Status:** Long-term goal (24+ months)
192
193**Concept:**
194Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:
195
196**Ownership Models:**
1971. **Shared Custody** - Multiple DIDs hold credentials (multisig)
1982. **Smart Contract Ownership** - On-chain DAO controls community
1993. **Federated Ownership** - Distributed across multiple instances
2004. **Delegated Ownership** - Community owned by a separate legal entity
201
202**Use Cases:**
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)
207
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?)
213
214---
215
216## Implementation Roadmap
217
218### Phase 1: V1 Role-Based System (Months 0-3)
219
220**Goals:**
221- Ship basic creator/moderator authorization
222- Enable self-hosted instances to delegate management
223- Foundation for all future governance features
224
225**Deliverables:**
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
237
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
243
244---
245
246### Phase 2: Moderator Permissions & Tiers (Months 3-6)
247
248**Goals:**
249- Add granular permission system
250- Support larger communities with specialized mod teams
251
252**Deliverables:**
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
260
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
265
266---
267
268### Phase 3: Democratic Governance (Months 6-18)
269
270**Goals:**
271- Enable opt-in democratic decision-making
272- Support voting on moderators and major community changes
273
274**Deliverables:**
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)
286
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
292
293---
294
295### Phase 4: Multi-Tenant Ownership (Months 18+)
296
297**Goals:**
298- Research and prototype shared ownership models
299- Enable communities backed by organizations/DAOs
300
301**Deliverables:**
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)
306
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
311
312---
313
314## Open Questions
315
316### Phase 1 (V1) Questions
3171. **Moderator limit:** Should there be a maximum number of moderators per community?
318 - **Recommendation:** Start with soft limit (e.g., 25), raise if needed
319
3202. **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
322
3233. **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
325
3264. **Creator transfer:** How to prevent accidental ownership transfers?
327 - **Recommendation:** Require confirmation from new creator before transfer completes
328
3295. **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)
331
332### Phase 2 (V2) Questions
3331. **Permission inheritance:** Do higher roles automatically include lower role permissions?
334 - Research standard forum software patterns
335
3362. **Permission UI:** How to make granular permissions understandable to non-technical users?
337 - Consider permission "bundles" or presets
338
3393. **Permission changes:** Can creator retroactively change moderator permissions?
340 - Should probably require confirmation/re-acceptance from moderator
341
342### Phase 3 (V3) Questions
3431. **Voter eligibility:** What constitutes "membership" for voting purposes?
344 - Active posters? Subscribers? Time-based (member for X days)?
345
3462. **Vote privacy:** Should votes be public or private?
347 - Public = transparent, but risk of social pressure
348 - Private = freedom, but harder to audit
349
3503. **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?
352
3534. **Governance defaults:** What happens to communities that don't explicitly configure governance?
354 - Fall back to V1 creator/moderator model
355
356### Phase 4 (V4) Questions
3571. **Credential custody:** Who physically holds the PDS credentials in multi-tenant scenario?
358 - Multisig wallet? Threshold encryption? Trusted third party?
359
3602. **Cost sharing:** How to split hosting costs across multiple owners?
361 - Smart contract? Legal entity? Manual coordination?
362
3633. **Conflict resolution:** What happens when co-owners disagree?
364 - Voting thresholds? Arbitration? Fork the community?
365
366---
367
368## Success Metrics
369
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)
375
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
380
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%
386
387---
388
389## Technical Decisions Log
390
391### 2025-10-11: Moderator Records Storage Location
392**Decision:** Store moderator records in community's repository (`at://community_did/social.coves.community.moderator/{tid}`), not user's repository
393
394**Rationale:**
3951. **Federation security**: Community's PDS can write/delete records in its own repo without cross-PDS coordination
3962. **Attack resistance**: Malicious self-hosted instances cannot forge or retain moderator status after revocation
3973. **Single source of truth**: Community's repo is authoritative; no need to check multiple repos + revocation lists
3984. **Instant revocation**: Deleting the record immediately removes moderator status across all instances
3995. **Simpler implementation**: No invitation flow, no multi-step acceptance, no revocation reconciliation
400
401**Security Analysis:**
402- **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
403- **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
404
405**Alternatives Considered:**
406- **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
407- **Hybrid (both repos)**: Assignment in community's repo + acceptance in user's repo provides consent without compromising security, but significantly increases complexity
408
409**Trade-offs Accepted:**
410- No explicit user consent (moderators are appointed, not invited)
411- Users cannot easily query "what do I moderate?" without AppView index
412- Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)
413
414**Implementation Notes:**
415- Moderator records are source of truth for permissions
416- AppView indexes these records from firehose for efficient querying
417- User consent can be added later via optional acceptance records without changing security model
418- Matches Bluesky's pattern: relationships in user's repo, service configuration in service's repo
419
420---
421
422### 2025-10-10: V1 Role-Based Model Selected
423**Decision:** Start with simple creator/moderator two-tier system
424
425**Rationale:**
426- Familiar to users (matches existing forum software)
427- Simple to implement on top of V2 architecture
428- Works for both centralized and self-hosted instances
429- Provides clear migration path to democratic governance
430- Avoids over-engineering before we understand actual usage patterns
431
432**Alternatives Considered:**
433- **atProto delegation:** More protocol-native, but spec is immature
434- **Multisig from day one:** Too complex, unclear user demand
435- **Single creator only:** Too limited for real-world use
436
437**Trade-offs Accepted:**
438- Won't support democratic governance initially
439- Creator still has ultimate authority (not truly decentralized)
440- Moderator permissions are coarse-grained
441
442---
443
444## Related PRDs
445
446- [PRD_COMMUNITIES.md](PRD_COMMUNITIES.md) - Core community architecture and V2 implementation
447- PRD_MODERATION.md (TODO) - Content moderation, reporting, labeling
448- PRD_FEDERATION.md (TODO) - Cross-instance community discovery and moderation
449
450---
451
452## References
453
454- atProto Authorization Spec: https://atproto.com/specs/xrpc#authentication
455- Bluesky Moderation System: https://docs.bsky.app/docs/advanced-guides/moderation
456- Reddit Moderator System: https://mods.reddithelp.com/hc/en-us/articles/360009381491
457- Discord Permission System: https://discord.com/developers/docs/topics/permissions
458- DAO Governance Patterns: https://ethereum.org/en/dao/