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 (Admins too?)
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## Architecture Evolution
33
34### V1: Role-Based Authorization (Recommended Starting Point)
35
36**Status:** Planned for initial implementation
37
38**Core Concept:**
39Three-tier permission model with clear role hierarchy:
40
41**Roles:**
421. **Creator** - Original community founder (DID from `createdBy` field)
43 - Full control: update profile, manage moderators, delete community
44 - Can transfer creator role to another user
45 - Only one creator per community at a time
46
472. **Moderator** - Trusted community managers
48 - Can update community profile (name, description, avatar, banner)
49 - Can manage community content (posts, members)
50 - Cannot delete community or manage other moderators
51 - Multiple moderators allowed per community
52
533. **Instance Admin** - Infrastructure operator (implicit role)
54 - Emergency override for legal/safety compliance
55 - Can delist, quarantine, or remove communities
56 - Should NOT be used for day-to-day community management
57 - Authority derived from instance DID matching `hostedBy`
58
59
60### V2: Moderator Tiers & Permissions
61
62**Status:** Future enhancement (6-12 months)
63
64**Concept:**
65Expand simple creator/moderator model with granular permissions:
66
67**Permission Types:**
68- `manage_profile` - Update name, description, images
69- `manage_content` - Moderate posts, remove content
70- `manage_members` - Ban users, manage reputation
71- `manage_moderators` - Add/remove other moderators
72- `manage_settings` - Change visibility, federation settings
73- `delete_community` - Permanent deletion
74
75**Moderator Tiers:**
76- **Full Moderator:** All permissions except `delete_community`
77- **Content Moderator:** Only `manage_content` and `manage_members`
78- **Settings Moderator:** Only `manage_profile` and `manage_settings`
79- **Custom:** Mix and match individual permissions
80
81**Use Cases:**
82- Large communities with specialized mod teams
83- Trial moderators with limited permissions
84- Automated bots with narrow scopes (e.g., spam removal)
85
86**Trade-offs:**
87- More flexible but significantly more complex
88- Harder to explain to users
89- More surface area for authorization bugs
90
91---
92
93### V3: Democratic Governance (Future Vision)
94
95**Status:** Long-term goal (12-24+ months)
96
97**Concept:**
98Communities can opt into democratic decision-making for major actions:
99
100**Governance Models:**
1011. **Direct Democracy** - All members vote on proposals
1022. **Representative** - Elected moderators serve fixed terms
1033. **Sortition** - Random selection of moderators from active members (like jury duty)
1044. **Hybrid** - Combination of elected + appointed moderators
105
106**Votable Actions:**
107- Adding/removing moderators
108- Updating community rules/guidelines
109- Changing visibility or federation settings
110- Migrating to a different instance
111- Transferring creator role
112- Deleting/archiving the community
113
114**Governance Configuration:**
115- Stored in `social.coves.community.profile` under `governance` field
116- Defines voting thresholds (e.g., 60% approval, 10% quorum)
117- Sets voting windows (e.g., 7-day voting period)
118- Specifies time locks (e.g., 3-day delay before execution)
119
120**Implementation Considerations:**
121- Requires on-chain or in-repository voting records for auditability
122- Needs sybil-resistance (prevent fake accounts from voting)
123- May require reputation/stake minimums to vote
124- Should support delegation (I assign my vote to someone else)
125
126**atProto Integration:**
127- Votes could be stored as records in community repository
128- Enables portable governance (votes migrate with community)
129- Allows external tools to verify governance legitimacy
130
131**Benefits:**
132- ✅ True community ownership
133- ✅ Democratic legitimacy for moderation decisions
134- ✅ Resistant to moderator abuse/corruption
135- ✅ Aligns with decentralization ethos
136
137**Challenges:**
138- ❌ Complex to implement correctly
139- ❌ Voting participation often low in practice
140- ❌ Vulnerable to brigading/vote manipulation
141- ❌ Slower decision-making (may be unacceptable for urgent moderation)
142- ❌ Legal/compliance issues (who's liable if community votes for illegal content?)
143
144---
145
146### V4: Multi-Tenant Ownership (Future Vision)
147
148**Status:** Long-term goal (24+ months)
149
150**Concept:**
151Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:
152
153**Ownership Models:**
1541. **Shared Custody** - Multiple DIDs hold credentials (multisig)
1552. **Smart Contract Ownership** - On-chain DAO controls community
1563. **Federated Ownership** - Distributed across multiple instances
1574. **Delegated Ownership** - Community owned by a separate legal entity
158
159**Use Cases:**
160- Large communities that span multiple instances
161- Communities backed by organizations/companies
162- Communities that need legal entity ownership
163- Cross-platform communities (exists on multiple protocols)
164
165**Technical Challenges:**
166- Credential management with multiple owners (who holds PDS password?)
167- Consensus on conflicting actions (one owner wants to delete, one doesn't)
168- Migration complexity (transferring ownership stakes)
169- Legal structure (who's liable, who pays hosting costs?)
170
171---
172
173## Content Rules System
174
175**Status:** Designed (2025-10-18)
176**Priority:** Alpha - Enables community-specific content policies
177
178### Overview
179
180Content rules allow communities to define restrictions on what types of content can be posted, replacing the rejected `postType` enum approach with flexible, structure-based validation.
181
182### Lexicon Design
183
184Content rules are stored in `social.coves.community.profile` under the `contentRules` object:
185
186```json
187{
188 "contentRules": {
189 "allowedEmbedTypes": ["images"], // Only images allowed
190 "requireText": true, // Posts must have text
191 "minTextLength": 50, // Minimum 50 characters
192 "maxTextLength": 5000, // Maximum 5000 characters
193 "requireTitle": false, // Title optional
194 "minImages": 1, // At least 1 image
195 "maxImages": 10, // Maximum 10 images
196 "allowFederated": false // No federated posts
197 }
198}
199```
200
201### Example Community Configurations
202
203**"AskCoves" - Text-Only Q&A:**
204```json
205{
206 "contentRules": {
207 "allowedEmbedTypes": [], // No embeds at all
208 "requireText": true,
209 "minTextLength": 50, // Substantive questions only
210 "requireTitle": true, // Must have question title
211 "allowFederated": false
212 }
213}
214```
215
216**"CovesPics" - Image Community:**
217```json
218{
219 "contentRules": {
220 "allowedEmbedTypes": ["images"],
221 "requireText": false, // Description optional
222 "minImages": 1, // Must have at least 1 image
223 "maxImages": 20,
224 "allowFederated": true // Allow Bluesky image posts
225 }
226}
227```
228
229**"CovesGeneral" - No Restrictions:**
230```json
231{
232 "contentRules": null // Or omit entirely - all content types allowed
233}
234```
235
236### Implementation Flow
237
2381. **Community Creation/Update:**
239 - Creator/moderator sets `contentRules` in community profile
240 - Rules stored in community's repository (`at://community_did/social.coves.community.profile/self`)
241 - AppView indexes rules for validation
242
2432. **Post Creation:**
244 - Handler receives post creation request
245 - Fetches community profile (including `contentRules`)
246 - Validates post structure against rules
247 - Returns `ContentRuleViolation` error if validation fails
248
2493. **Validation Logic:**
250 - Check embed types against `allowedEmbedTypes`
251 - Verify text requirements (`requireText`, `minTextLength`, `maxTextLength`)
252 - Check title requirements (`requireTitle`)
253 - Validate image counts (`minImages`, `maxImages`)
254 - Block federated posts if `allowFederated: false`
255
2564. **User Filtering (Client-Side):**
257 - AppView indexes derived post characteristics (has_embed, embed_type, text_length)
258 - UI can filter "show only videos" or "show only text posts"
259 - Filters don't need protocol support - just AppView queries
260
261### Benefits Over `postType` Enum
262
263✅ **More Flexible:** Communities can define granular rules (e.g., "text required but images optional")
264✅ **Extensible:** Add new rules without changing post lexicon
265✅ **Federation-Friendly:** Rules describe structure, not arbitrary types
266✅ **Client Freedom:** Different clients interpret same data differently
267✅ **Separation of Concerns:** Post structure (protocol) vs. community policy (governance)
268
269### Security Considerations
270
271- **Validation is advisory:** Malicious PDS could ignore rules, but AppView can filter out violating posts
272- **Rate limiting:** Prevent spam of posts that get rejected for rule violations
273- **Audit logging:** Track rule violations for moderation review
274
275---
276
277## Implementation Roadmap
278
279### Phase 0: Content Rules System (Month 0 - Alpha Blocker)
280
281**Status:** Lexicon complete, implementation TODO
282**Priority:** CRITICAL - Required for alpha launch
283
284**Goals:**
285- Enable communities to restrict content types
286- Validate posts against community rules
287- Support common use cases (text-only, images-only, etc.)
288
289**Deliverables:**
290- [x] Lexicon: `contentRules` object in `social.coves.community.profile` ✅
291- [ ] Go structs: `ContentRules` type in community models
292- [ ] Repository: Parse and store `contentRules` from community profiles
293- [ ] Service: `ValidatePostAgainstRules(post, community)` function
294- [ ] Handler: Integrate validation into `social.coves.community.post.create`
295- [ ] AppView indexing: Index post characteristics (embed_type, text_length, etc.)
296- [ ] Tests: Comprehensive rule validation tests
297- [ ] Documentation: Content rules guide for community creators
298
299**Success Criteria:**
300- "AskCoves" text-only community rejects image posts
301- "CovesPics" image community requires at least one image
302- Validation errors are clear and actionable
303- No performance impact on post creation (< 10ms validation)
304
305---
306
307### Phase 1: V1 Role-Based System (Months 0-3)
308
309**Goals:**
310- Ship basic creator/moderator authorization
311- Enable self-hosted instances to delegate management
312- Foundation for all future governance features
313
314**Deliverables:**
315- [ ] Database schema: `community_moderators` table
316- [ ] Repository layer: CRUD for moderator records
317- [ ] Service layer: Authorization checks for all operations
318- [ ] XRPC endpoints:
319 - [ ] `social.coves.community.addModerator`
320 - [ ] `social.coves.community.removeModerator`
321 - [ ] `social.coves.community.listModerators`
322 - [ ] `social.coves.community.transferOwnership`
323- [ ] Middleware: Role-based authorization for existing endpoints
324- [ ] Tests: Integration tests for all permission scenarios
325- [ ] Documentation: API docs, governance guide for instance admins
326
327**Success Criteria:**
328- Community creators can add/remove moderators
329- Moderators can update community profile (including content rules) but not delete
330- Authorization prevents unauthorized operations
331- Works seamlessly for both centralized and self-hosted instances
332
333---
334
335### Phase 2: Moderator Permissions & Tiers (Months 3-6)
336
337**Goals:**
338- Add granular permission system
339- Support larger communities with specialized mod teams
340
341**Deliverables:**
342- [ ] Schema: Add `permissions` JSON column to `community_moderators`
343- [ ] Permission framework: Define and validate permission sets
344- [ ] XRPC endpoints:
345 - [ ] `social.coves.community.updateModeratorPermissions`
346 - [ ] `social.coves.community.getModeratorPermissions`
347- [ ] UI-friendly permission presets (Full Mod, Content Mod, etc.)
348- [ ] Audit logging: Track permission changes and usage
349
350**Success Criteria:**
351- Communities can create custom moderator roles
352- Permission checks prevent unauthorized operations
353- Clear audit trail of who did what with which permissions
354
355---
356
357### Phase 3: Democratic Governance (Months 6-18)
358
359**Goals:**
360- Enable opt-in democratic decision-making
361- Support voting on moderators and major community changes
362
363**Deliverables:**
364- [ ] Governance framework: Define votable actions and thresholds
365- [ ] Voting system: Proposal creation, voting, execution
366- [ ] Sybil resistance: Require minimum reputation/activity to vote
367- [ ] Lexicon: `social.coves.community.proposal` and `social.coves.community.vote`
368- [ ] XRPC endpoints:
369 - [ ] `social.coves.community.createProposal`
370 - [ ] `social.coves.community.vote`
371 - [ ] `social.coves.community.executeProposal`
372 - [ ] `social.coves.community.listProposals`
373- [ ] Time locks and voting windows
374- [ ] Delegation system (optional)
375
376**Success Criteria:**
377- Communities can opt into democratic governance
378- Proposals can be created, voted on, and executed
379- Voting records are portable (stored in repository)
380- System prevents vote manipulation
381
382---
383
384### Phase 4: Multi-Tenant Ownership (Months 18+)
385
386**Goals:**
387- Research and prototype shared ownership models
388- Enable communities backed by organizations/DAOs
389
390**Deliverables:**
391- [ ] Research: Survey existing DAO/multisig solutions
392- [ ] Prototype: Multisig credential management
393- [ ] Legal review: Liability and compliance considerations
394- [ ] Integration: Bridge to existing DAO platforms (if applicable)
395
396**Success Criteria:**
397- Proof of concept for shared ownership
398- Clear legal framework for multi-tenant communities
399- Migration path from single-owner to multi-owner
400
401---
402
403## Open Questions
404
405### Phase 1 (V1) Questions
4061. **Moderator limit:** Should there be a maximum number of moderators per community?
407 - **Recommendation:** Start with soft limit (e.g., 25), raise if needed
408
4092. **Moderator-added moderators:** Can moderators add other moderators, or only the creator?
410 - **Recommendation:** Creator-only to start (simpler), add in Phase 2 if needed
411
4123. **Moderator storage:** Store moderator list in atProto repository or just AppView DB?
413 - **Recommendation:** AppView DB initially (faster), add repository sync in Phase 2 for portability
414
4154. **Creator transfer:** How to prevent accidental ownership transfers?
416 - **Recommendation:** Require confirmation from new creator before transfer completes
417
4185. **Inactive creators:** How to handle communities where creator is gone/inactive?
419 - **Recommendation:** Instance admin emergency transfer after X months inactivity (define in Phase 2)
420
421### Phase 2 (V2) Questions
4221. **Permission inheritance:** Do higher roles automatically include lower role permissions?
423 - Research standard forum software patterns
424
4252. **Permission UI:** How to make granular permissions understandable to non-technical users?
426 - Consider permission "bundles" or presets
427
4283. **Permission changes:** Can creator retroactively change moderator permissions?
429 - Should probably require confirmation/re-acceptance from moderator
430
431### Phase 3 (V3) Questions
4321. **Voter eligibility:** What constitutes "membership" for voting purposes?
433 - Active posters? Subscribers? Time-based (member for X days)?
434
4352. **Vote privacy:** Should votes be public or private?
436 - Public = transparent, but risk of social pressure
437 - Private = freedom, but harder to audit
438
4393. **Emergency override:** Can instance still moderate if community votes for illegal content?
440 - Yes (instance liability), but how to make this clear and minimize abuse?
441
4424. **Governance defaults:** What happens to communities that don't explicitly configure governance?
443 - Fall back to V1 creator/moderator model
444
445### Phase 4 (V4) Questions
4461. **Credential custody:** Who physically holds the PDS credentials in multi-tenant scenario?
447 - Multisig wallet? Threshold encryption? Trusted third party?
448
4492. **Cost sharing:** How to split hosting costs across multiple owners?
450 - Smart contract? Legal entity? Manual coordination?
451
4523. **Conflict resolution:** What happens when co-owners disagree?
453 - Voting thresholds? Arbitration? Fork the community?
454
455---
456
457## Success Metrics
458
459### V1 Launch Metrics
460- [ ] 90%+ of self-hosted instances create at least one community
461- [ ] Average 2+ moderators per active community
462- [ ] Zero authorization bypass bugs in production
463- [ ] Creator → Moderator permission model understandable to users (< 5% support tickets about roles)
464
465### V2 Adoption Metrics
466- [ ] 20%+ of communities use custom permission sets
467- [ ] Zero permission escalation vulnerabilities
468- [ ] Audit logs successfully resolve 90%+ of disputes
469
470### V3 Governance Metrics
471- [ ] 10%+ of communities opt into democratic governance
472- [ ] Average voter turnout > 20% for major decisions
473- [ ] < 5% of votes successfully manipulated/brigaded
474- [ ] Community satisfaction with governance process > 70%
475
476---
477
478## Technical Decisions Log
479
480### 2025-10-11: Moderator Records Storage Location
481**Decision:** Store moderator records in community's repository (`at://community_did/social.coves.community.moderator/{tid}`), not user's repository
482
483**Rationale:**
4841. **Federation security**: Community's PDS can write/delete records in its own repo without cross-PDS coordination
4852. **Attack resistance**: Malicious self-hosted instances cannot forge or retain moderator status after revocation
4863. **Single source of truth**: Community's repo is authoritative; no need to check multiple repos + revocation lists
4874. **Instant revocation**: Deleting the record immediately removes moderator status across all instances
4885. **Simpler implementation**: No invitation flow, no multi-step acceptance, no revocation reconciliation
489
490**Security Analysis:**
491- **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
492- **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
493
494**Alternatives Considered:**
495- **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
496- **Hybrid (both repos)**: Assignment in community's repo + acceptance in user's repo provides consent without compromising security, but significantly increases complexity
497
498**Trade-offs Accepted:**
499- No explicit user consent (moderators are appointed, not invited)
500- Users cannot easily query "what do I moderate?" without AppView index
501- Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)
502
503**Implementation Notes:**
504- Moderator records are source of truth for permissions
505- AppView indexes these records from firehose for efficient querying
506- User consent can be added later via optional acceptance records without changing security model
507- Matches Bluesky's pattern: relationships in user's repo, service configuration in service's repo
508
509---
510
511### 2025-10-10: V1 Role-Based Model Selected
512**Decision:** Start with simple creator/moderator two-tier system
513
514**Rationale:**
515- Familiar to users (matches existing forum software)
516- Simple to implement on top of V2 architecture
517- Works for both centralized and self-hosted instances
518- Provides clear migration path to democratic governance
519- Avoids over-engineering before we understand actual usage patterns
520
521**Alternatives Considered:**
522- **atProto delegation:** More protocol-native, but spec is immature
523- **Multisig from day one:** Too complex, unclear user demand
524- **Single creator only:** Too limited for real-world use
525
526**Trade-offs Accepted:**
527- Won't support democratic governance initially
528- Creator still has ultimate authority (not truly decentralized)
529- Moderator permissions are coarse-grained
530
531---
532
533## Related PRDs
534
535- [PRD_COMMUNITIES.md](PRD_COMMUNITIES.md) - Core community architecture and V2 implementation
536- PRD_MODERATION.md (TODO) - Content moderation, reporting, labeling
537- PRD_FEDERATION.md (TODO) - Cross-instance community discovery and moderation
538
539---
540
541## References
542
543- atProto Authorization Spec: https://atproto.com/specs/xrpc#authentication
544- Bluesky Moderation System: https://docs.bsky.app/docs/advanced-guides/moderation
545- Reddit Moderator System: https://mods.reddithelp.com/hc/en-us/articles/360009381491
546- Discord Permission System: https://discord.com/developers/docs/topics/permissions
547- DAO Governance Patterns: https://ethereum.org/en/dao/