Governance PRD: Community Ownership & Moderation#

Status: Planning / Not Started Owner: Platform Team Last Updated: 2025-10-10

Overview#

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.

The governance system must balance three competing needs:

Community autonomy - Communities should self-govern where possible
Instance control - Hosting instances need moderation/compliance powers
User experience - Clear, understandable permissions that work for self-hosted and centralized deployments

Problem Statement#

Current State (2025-10-15):

Communities own their own atProto repositories (V2 architecture)
Instance holds PDS credentials for infrastructure management
Basic authorization exists: only createdBy user can update communities (Admins too?)
No moderator management system exists yet

Note: Moderator management and advanced governance are post-alpha (Beta Phase 1) work. Alpha focuses on basic community CRUD operations.

Key Issues:

Self-hosted instances: Instance operator can't delegate community management to trusted users
Community lifecycle: No way to transfer ownership or add co-managers
Scaling moderation: Single-owner model doesn't scale to large communities
User expectations: Forum users expect moderator teams, not single-admin models

Architecture Evolution#

V1: Role-Based Authorization (Recommended Starting Point)#

Status: Planned for initial implementation

Core Concept: Three-tier permission model with clear role hierarchy:

Roles:

Creator - Original community founder (DID from createdBy field)
- Full control: update profile, manage moderators, delete community
- Can transfer creator role to another user
- Only one creator per community at a time
Moderator - Trusted community managers
- Can update community profile (name, description, avatar, banner)
- Can manage community content (posts, members)
- Cannot delete community or manage other moderators
- Multiple moderators allowed per community
Instance Admin - Infrastructure operator (implicit role)
- Emergency override for legal/safety compliance
- Can delist, quarantine, or remove communities
- Should NOT be used for day-to-day community management
- Authority derived from instance DID matching hostedBy

V2: Moderator Tiers & Permissions#

Status: Future enhancement (6-12 months)

Concept: Expand simple creator/moderator model with granular permissions:

Permission Types:

manage_profile - Update name, description, images
manage_content - Moderate posts, remove content
manage_members - Ban users, manage reputation
manage_moderators - Add/remove other moderators
manage_settings - Change visibility, federation settings
delete_community - Permanent deletion

Moderator Tiers:

Full Moderator: All permissions except delete_community
Content Moderator: Only manage_content and manage_members
Settings Moderator: Only manage_profile and manage_settings
Custom: Mix and match individual permissions

Use Cases:

Large communities with specialized mod teams
Trial moderators with limited permissions
Automated bots with narrow scopes (e.g., spam removal)

Trade-offs:

More flexible but significantly more complex
Harder to explain to users
More surface area for authorization bugs

V3: Democratic Governance (Future Vision)#

Status: Long-term goal (12-24+ months)

Concept: Communities can opt into democratic decision-making for major actions:

Governance Models:

Direct Democracy - All members vote on proposals
Representative - Elected moderators serve fixed terms
Sortition - Random selection of moderators from active members (like jury duty)
Hybrid - Combination of elected + appointed moderators

Votable Actions:

Adding/removing moderators
Updating community rules/guidelines
Changing visibility or federation settings
Migrating to a different instance
Transferring creator role
Deleting/archiving the community

Governance Configuration:

Stored in social.coves.community.profile under governance field
Defines voting thresholds (e.g., 60% approval, 10% quorum)
Sets voting windows (e.g., 7-day voting period)
Specifies time locks (e.g., 3-day delay before execution)

Implementation Considerations:

Requires on-chain or in-repository voting records for auditability
Needs sybil-resistance (prevent fake accounts from voting)
May require reputation/stake minimums to vote
Should support delegation (I assign my vote to someone else)

atProto Integration:

Votes could be stored as records in community repository
Enables portable governance (votes migrate with community)
Allows external tools to verify governance legitimacy

Benefits:

✅ True community ownership
✅ Democratic legitimacy for moderation decisions
✅ Resistant to moderator abuse/corruption
✅ Aligns with decentralization ethos

Challenges:

❌ Complex to implement correctly
❌ Voting participation often low in practice
❌ Vulnerable to brigading/vote manipulation
❌ Slower decision-making (may be unacceptable for urgent moderation)
❌ Legal/compliance issues (who's liable if community votes for illegal content?)

V4: Multi-Tenant Ownership (Future Vision)#

Status: Long-term goal (24+ months)

Concept: Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:

Ownership Models:

Shared Custody - Multiple DIDs hold credentials (multisig)
Smart Contract Ownership - On-chain DAO controls community
Federated Ownership - Distributed across multiple instances
Delegated Ownership - Community owned by a separate legal entity

Use Cases:

Large communities that span multiple instances
Communities backed by organizations/companies
Communities that need legal entity ownership
Cross-platform communities (exists on multiple protocols)

Technical Challenges:

Credential management with multiple owners (who holds PDS password?)
Consensus on conflicting actions (one owner wants to delete, one doesn't)
Migration complexity (transferring ownership stakes)
Legal structure (who's liable, who pays hosting costs?)

Content Rules System#

Status: Designed (2025-10-18) Priority: Alpha - Enables community-specific content policies

Overview#

Content 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.

Lexicon Design#

Content rules are stored in social.coves.community.profile under the contentRules object:

{
  "contentRules": {
    "allowedEmbedTypes": ["images"],      // Only images allowed
    "requireText": true,                   // Posts must have text
    "minTextLength": 50,                   // Minimum 50 characters
    "maxTextLength": 5000,                 // Maximum 5000 characters
    "requireTitle": false,                 // Title optional
    "minImages": 1,                        // At least 1 image
    "maxImages": 10,                       // Maximum 10 images
    "allowFederated": false                // No federated posts
  }
}

Example Community Configurations#

"AskCoves" - Text-Only Q&A:

{
  "contentRules": {
    "allowedEmbedTypes": [],       // No embeds at all
    "requireText": true,
    "minTextLength": 50,           // Substantive questions only
    "requireTitle": true,          // Must have question title
    "allowFederated": false
  }
}

"CovesPics" - Image Community:

{
  "contentRules": {
    "allowedEmbedTypes": ["images"],
    "requireText": false,          // Description optional
    "minImages": 1,                // Must have at least 1 image
    "maxImages": 20,
    "allowFederated": true         // Allow Bluesky image posts
  }
}

"CovesGeneral" - No Restrictions:

{
  "contentRules": null  // Or omit entirely - all content types allowed
}

Implementation Flow#

Community Creation/Update:
- Creator/moderator sets contentRules in community profile
- Rules stored in community's repository (at://community_did/social.coves.community.profile/self)
- AppView indexes rules for validation
Post Creation:
- Handler receives post creation request
- Fetches community profile (including contentRules)
- Validates post structure against rules
- Returns ContentRuleViolation error if validation fails
Validation Logic:
- Check embed types against allowedEmbedTypes
- Verify text requirements (requireText, minTextLength, maxTextLength)
- Check title requirements (requireTitle)
- Validate image counts (minImages, maxImages)
- Block federated posts if allowFederated: false
User Filtering (Client-Side):
- AppView indexes derived post characteristics (has_embed, embed_type, text_length)
- UI can filter "show only videos" or "show only text posts"
- Filters don't need protocol support - just AppView queries

Benefits Over `postType` Enum#

✅ More Flexible: Communities can define granular rules (e.g., "text required but images optional") ✅ Extensible: Add new rules without changing post lexicon ✅ Federation-Friendly: Rules describe structure, not arbitrary types ✅ Client Freedom: Different clients interpret same data differently ✅ Separation of Concerns: Post structure (protocol) vs. community policy (governance)

Security Considerations#

Validation is advisory: Malicious PDS could ignore rules, but AppView can filter out violating posts
Rate limiting: Prevent spam of posts that get rejected for rule violations
Audit logging: Track rule violations for moderation review

Implementation Roadmap#

Phase 0: Content Rules System (Month 0 - Alpha Blocker)#

Status: Lexicon complete, implementation TODO Priority: CRITICAL - Required for alpha launch

Goals:

Enable communities to restrict content types
Validate posts against community rules
Support common use cases (text-only, images-only, etc.)

Deliverables:

Lexicon: contentRules object in social.coves.community.profile ✅
Go structs: ContentRules type in community models
Repository: Parse and store contentRules from community profiles
Service: ValidatePostAgainstRules(post, community) function
Handler: Integrate validation into social.coves.community.post.create
AppView indexing: Index post characteristics (embed_type, text_length, etc.)
Tests: Comprehensive rule validation tests
Documentation: Content rules guide for community creators

Success Criteria:

"AskCoves" text-only community rejects image posts
"CovesPics" image community requires at least one image
Validation errors are clear and actionable
No performance impact on post creation (< 10ms validation)

Phase 1: V1 Role-Based System (Months 0-3)#

Goals:

Ship basic creator/moderator authorization
Enable self-hosted instances to delegate management
Foundation for all future governance features

Deliverables:

Database schema: community_moderators table
Repository layer: CRUD for moderator records
Service layer: Authorization checks for all operations
XRPC endpoints:
- social.coves.community.addModerator
- social.coves.community.removeModerator
- social.coves.community.listModerators
- social.coves.community.transferOwnership
Middleware: Role-based authorization for existing endpoints
Tests: Integration tests for all permission scenarios
Documentation: API docs, governance guide for instance admins

Success Criteria:

Community creators can add/remove moderators
Moderators can update community profile (including content rules) but not delete
Authorization prevents unauthorized operations
Works seamlessly for both centralized and self-hosted instances

Phase 2: Moderator Permissions & Tiers (Months 3-6)#

Goals:

Add granular permission system
Support larger communities with specialized mod teams

Deliverables:

Schema: Add permissions JSON column to community_moderators
Permission framework: Define and validate permission sets
XRPC endpoints:
- social.coves.community.updateModeratorPermissions
- social.coves.community.getModeratorPermissions
UI-friendly permission presets (Full Mod, Content Mod, etc.)
Audit logging: Track permission changes and usage

Success Criteria:

Communities can create custom moderator roles
Permission checks prevent unauthorized operations
Clear audit trail of who did what with which permissions

Phase 3: Democratic Governance (Months 6-18)#

Goals:

Enable opt-in democratic decision-making
Support voting on moderators and major community changes

Deliverables:

Governance framework: Define votable actions and thresholds
Voting system: Proposal creation, voting, execution
Sybil resistance: Require minimum reputation/activity to vote
Lexicon: social.coves.community.proposal and social.coves.community.vote
XRPC endpoints:
- social.coves.community.createProposal
- social.coves.community.vote
- social.coves.community.executeProposal
- social.coves.community.listProposals
Time locks and voting windows
Delegation system (optional)

Success Criteria:

Communities can opt into democratic governance
Proposals can be created, voted on, and executed
Voting records are portable (stored in repository)
System prevents vote manipulation

Phase 4: Multi-Tenant Ownership (Months 18+)#

Goals:

Research and prototype shared ownership models
Enable communities backed by organizations/DAOs

Deliverables:

Research: Survey existing DAO/multisig solutions
Prototype: Multisig credential management
Legal review: Liability and compliance considerations
Integration: Bridge to existing DAO platforms (if applicable)

Success Criteria:

Proof of concept for shared ownership
Clear legal framework for multi-tenant communities
Migration path from single-owner to multi-owner

Open Questions#

Phase 1 (V1) Questions#

Moderator limit: Should there be a maximum number of moderators per community?
- Recommendation: Start with soft limit (e.g., 25), raise if needed
Moderator-added moderators: Can moderators add other moderators, or only the creator?
- Recommendation: Creator-only to start (simpler), add in Phase 2 if needed
Moderator storage: Store moderator list in atProto repository or just AppView DB?
- Recommendation: AppView DB initially (faster), add repository sync in Phase 2 for portability
Creator transfer: How to prevent accidental ownership transfers?
- Recommendation: Require confirmation from new creator before transfer completes
Inactive creators: How to handle communities where creator is gone/inactive?
- Recommendation: Instance admin emergency transfer after X months inactivity (define in Phase 2)

Phase 2 (V2) Questions#

Permission inheritance: Do higher roles automatically include lower role permissions?
- Research standard forum software patterns
Permission UI: How to make granular permissions understandable to non-technical users?
- Consider permission "bundles" or presets
Permission changes: Can creator retroactively change moderator permissions?
- Should probably require confirmation/re-acceptance from moderator

Phase 3 (V3) Questions#

Voter eligibility: What constitutes "membership" for voting purposes?
- Active posters? Subscribers? Time-based (member for X days)?
Vote privacy: Should votes be public or private?
- Public = transparent, but risk of social pressure
- Private = freedom, but harder to audit
Emergency override: Can instance still moderate if community votes for illegal content?
- Yes (instance liability), but how to make this clear and minimize abuse?
Governance defaults: What happens to communities that don't explicitly configure governance?
- Fall back to V1 creator/moderator model

Phase 4 (V4) Questions#

Credential custody: Who physically holds the PDS credentials in multi-tenant scenario?
- Multisig wallet? Threshold encryption? Trusted third party?
Cost sharing: How to split hosting costs across multiple owners?
- Smart contract? Legal entity? Manual coordination?
Conflict resolution: What happens when co-owners disagree?
- Voting thresholds? Arbitration? Fork the community?

Success Metrics#

V1 Launch Metrics#

90%+ of self-hosted instances create at least one community
Average 2+ moderators per active community
Zero authorization bypass bugs in production
Creator → Moderator permission model understandable to users (< 5% support tickets about roles)

V2 Adoption Metrics#

20%+ of communities use custom permission sets
Zero permission escalation vulnerabilities
Audit logs successfully resolve 90%+ of disputes

V3 Governance Metrics#

10%+ of communities opt into democratic governance
Average voter turnout > 20% for major decisions
< 5% of votes successfully manipulated/brigaded
Community satisfaction with governance process > 70%

Technical Decisions Log#

2025-10-11: Moderator Records Storage Location#

Decision: Store moderator records in community's repository (at://community_did/social.coves.community.moderator/{tid}), not user's repository

Rationale:

Federation security: Community's PDS can write/delete records in its own repo without cross-PDS coordination
Attack resistance: Malicious self-hosted instances cannot forge or retain moderator status after revocation
Single source of truth: Community's repo is authoritative; no need to check multiple repos + revocation lists
Instant revocation: Deleting the record immediately removes moderator status across all instances
Simpler implementation: No invitation flow, no multi-step acceptance, no revocation reconciliation

Security Analysis:

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
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

Alternatives Considered:

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
Hybrid (both repos): Assignment in community's repo + acceptance in user's repo provides consent without compromising security, but significantly increases complexity

Trade-offs Accepted:

No explicit user consent (moderators are appointed, not invited)
Users cannot easily query "what do I moderate?" without AppView index
Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)

Implementation Notes:

Moderator records are source of truth for permissions
AppView indexes these records from firehose for efficient querying
User consent can be added later via optional acceptance records without changing security model
Matches Bluesky's pattern: relationships in user's repo, service configuration in service's repo

2025-10-10: V1 Role-Based Model Selected#

Decision: Start with simple creator/moderator two-tier system

Rationale:

Familiar to users (matches existing forum software)
Simple to implement on top of V2 architecture
Works for both centralized and self-hosted instances
Provides clear migration path to democratic governance
Avoids over-engineering before we understand actual usage patterns

Alternatives Considered:

atProto delegation: More protocol-native, but spec is immature
Multisig from day one: Too complex, unclear user demand
Single creator only: Too limited for real-world use

Trade-offs Accepted:

Won't support democratic governance initially
Creator still has ultimate authority (not truly decentralized)
Moderator permissions are coarse-grained

PRD_COMMUNITIES.md - Core community architecture and V2 implementation
PRD_MODERATION.md (TODO) - Content moderation, reporting, labeling
PRD_FEDERATION.md (TODO) - Cross-instance community discovery and moderation

References#

atProto Authorization Spec: https://atproto.com/specs/xrpc#authentication
Bluesky Moderation System: https://docs.bsky.app/docs/advanced-guides/moderation
Reddit Moderator System: https://mods.reddithelp.com/hc/en-us/articles/360009381491
Discord Permission System: https://discord.com/developers/docs/topics/permissions
DAO Governance Patterns: https://ethereum.org/en/dao/

Governance PRD: Community Ownership & Moderation#

Overview#

Problem Statement#

Architecture Evolution#

V1: Role-Based Authorization (Recommended Starting Point)#

V2: Moderator Tiers & Permissions#

V3: Democratic Governance (Future Vision)#

V4: Multi-Tenant Ownership (Future Vision)#

Content Rules System#

Overview#

Lexicon Design#

Example Community Configurations#

Implementation Flow#

Benefits Over postType Enum#

Security Considerations#

Implementation Roadmap#

Phase 0: Content Rules System (Month 0 - Alpha Blocker)#

Phase 1: V1 Role-Based System (Months 0-3)#

Phase 2: Moderator Permissions & Tiers (Months 3-6)#

Phase 3: Democratic Governance (Months 6-18)#

Phase 4: Multi-Tenant Ownership (Months 18+)#

Open Questions#

Phase 1 (V1) Questions#

Phase 2 (V2) Questions#

Phase 3 (V3) Questions#

Phase 4 (V4) Questions#

Success Metrics#

V1 Launch Metrics#

V2 Adoption Metrics#

V3 Governance Metrics#

Technical Decisions Log#

2025-10-11: Moderator Records Storage Location#

2025-10-10: V1 Role-Based Model Selected#

Related PRDs#

References#

Benefits Over `postType` Enum#