commit addc76504ff223089720943f785aef62f18b1826 · bretton.dev/coves

+59 -4

docs/PRD_BACKLOG.md

···

       26
        
       

     

       27
        
       ---

     

       28
        
       

     

       29
       -
       ## 🟡 P1: Important

     

       30
        
       

     

       31
        
       ### Token Refresh Logic for Community Credentials

     

       32
       -
       **Added:** 2025-10-11 | **Effort:** 1-2 days

     

       33
        
       

     

       34
        
       **Problem:** Community PDS access tokens expire (~2hrs). Updates fail until manual intervention.

     

       35
        
       

     
···

       40
        
       ---

     

       41
        
       

     

       42
        
       ### OAuth Authentication for Community Actions

     

       43
       -
       **Added:** 2025-10-11 | **Effort:** 2-3 days

     

       44
        
       

     

       45
        
       **Problem:** Subscribe/unsubscribe and community creation need authenticated user DID. Currently using placeholder.

     

       46
        
       

     

       47
        
       **Solution:** Extract authenticated DID from OAuth session context. Requires OAuth middleware integration.

     

       48
        
       

     

       49
       -
       **Code:** Multiple TODOs in [community/subscribe.go](../internal/api/handlers/community/subscribe.go#L46), [community/create.go](../internal/api/handlers/community/create.go#L38)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       50
        
       

     

       51
        
       ---

     

       52
        
       

     

       53
        
       ## 🟢 P2: Nice-to-Have

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       54
        
       

     

       55
        
       ### Improve .local TLD Error Messages

     

       56
        
       **Added:** 2025-10-11 | **Effort:** 1 hour

···

       26
        
       

     

       27
        
       ---

     

       28
        
       

     

       29
       +
       ## 🟡 P1: Important (Alpha Blockers)

     

       30
        
       

     

       31
        
       ### Token Refresh Logic for Community Credentials

     

       32
       +
       **Added:** 2025-10-11 | **Effort:** 1-2 days | **Priority:** ALPHA BLOCKER

     

       33
        
       

     

       34
        
       **Problem:** Community PDS access tokens expire (~2hrs). Updates fail until manual intervention.

     

       35
        
       

     
···

       40
        
       ---

     

       41
        
       

     

       42
        
       ### OAuth Authentication for Community Actions

     

       43
       +
       **Added:** 2025-10-11 | **Effort:** 2-3 days | **Priority:** ALPHA BLOCKER

     

       44
        
       

     

       45
        
       **Problem:** Subscribe/unsubscribe and community creation need authenticated user DID. Currently using placeholder.

     

       46
        
       

     

       47
        
       **Solution:** Extract authenticated DID from OAuth session context. Requires OAuth middleware integration.

     

       48
        
       

     

       49
       +
       **Code:** Multiple TODOs in [community/subscribe.go](../internal/api/handlers/community/subscribe.go#L46), [community/create.go](../internal/api/handlers/community/create.go#L38), [community/update.go](../internal/api/handlers/community/update.go#L47)

     

       50
       +
       

     

       51
       +
       ---

     

       52
       +
       

     

       53
       +
       ### Subscription Visibility Level (Feed Slider 1-5 Scale)

     

       54
       +
       **Added:** 2025-10-15 | **Effort:** 4-6 hours | **Priority:** ALPHA BLOCKER

     

       55
       +
       

     

       56
       +
       **Problem:** Users can't control how much content they see from each community. Lexicon has `contentVisibility` (1-5 scale) but code doesn't use it.

     

       57
       +
       

     

       58
       +
       **Solution:**

     

       59
       +
       - Update subscribe handler to accept `contentVisibility` parameter (1-5, default 3)

     

       60
       +
       - Store in subscription record on PDS

     

       61
       +
       - Update feed generation to respect visibility level (beta work, but data structure needed now)

     

       62
       +
       

     

       63
       +
       **Code:**

     

       64
       +
       - Lexicon: [subscription.json:28-34](../internal/atproto/lexicon/social/coves/actor/subscription.json#L28-L34) ✅ Ready

     

       65
       +
       - Handler: [community/subscribe.go](../internal/api/handlers/community/subscribe.go) - Add parameter

     

       66
       +
       - Service: [communities/service.go:373-376](../internal/core/communities/service.go#L373-L376) - Add to record

     

       67
       +
       

     

       68
       +
       **Impact:** Without this, users have no way to adjust feed volume per community (key feature from DOMAIN_KNOWLEDGE.md)

     

       69
       +
       

     

       70
       +
       ---

     

       71
       +
       

     

       72
       +
       ### Community Blocking

     

       73
       +
       **Added:** 2025-10-15 | **Effort:** 1 day | **Priority:** ALPHA BLOCKER

     

       74
       +
       

     

       75
       +
       **Problem:** Users have no way to block unwanted communities from their feeds.

     

       76
       +
       

     

       77
       +
       **Solution:**

     

       78
       +
       1. **Lexicon:** Extend `social.coves.actor.block` to support community DIDs (currently user-only)

     

       79
       +
       2. **Service:** Implement `BlockCommunity(userDID, communityDID)` and `UnblockCommunity()`

     

       80
       +
       3. **Handlers:** Add XRPC endpoints `social.coves.community.block` and `unblock`

     

       81
       +
       4. **Repository:** Add methods to track blocked communities

     

       82
       +
       5. **Feed:** Filter blocked communities from feed queries (beta work)

     

       83
       +
       

     

       84
       +
       **Code:**

     

       85
       +
       - Lexicon: [actor/block.json](../internal/atproto/lexicon/social/coves/actor/block.json) - Currently only supports user DIDs

     

       86
       +
       - Service: New methods needed

     

       87
       +
       - Handlers: New files needed

     

       88
       +
       

     

       89
       +
       **Impact:** Users can't avoid unwanted content without blocking

     

       90
        
       

     

       91
        
       ---

     

       92
        
       

     

       93
        
       ## 🟢 P2: Nice-to-Have

     

       94
       +
       

     

       95
       +
       ### Remove Categories from Community Lexicon

     

       96
       +
       **Added:** 2025-10-15 | **Effort:** 30 minutes | **Priority:** Cleanup

     

       97
       +
       

     

       98
       +
       **Problem:** Categories field exists in create/update lexicon but not in profile record. Adds complexity without clear value.

     

       99
       +
       

     

       100
       +
       **Solution:**

     

       101
       +
       - Remove `categories` from [create.json](../internal/atproto/lexicon/social/coves/community/create.json#L46-L54)

     

       102
       +
       - Remove `categories` from [update.json](../internal/atproto/lexicon/social/coves/community/update.json#L51-L59)

     

       103
       +
       - Remove from [community.go:91](../internal/core/communities/community.go#L91)

     

       104
       +
       - Remove from service layer ([service.go:109-110](../internal/core/communities/service.go#L109-L110))

     

       105
       +
       

     

       106
       +
       **Impact:** Simplifies lexicon, removes unused feature

     

       107
       +
       

     

       108
       +
       ---

     

       109
        
       

     

       110
        
       ### Improve .local TLD Error Messages

     

       111
        
       **Added:** 2025-10-11 | **Effort:** 1 hour

+82 -41

docs/PRD_COMMUNITIES.md

···

       89
        
       ## 🚧 In Progress / Needs Testing

     

       90
        
       

     

       91
        
       ### XRPC API Endpoints

     

       92
       -
       **Status:** Handlers exist, need comprehensive E2E testing

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       93
        
       

     

       94
       -
       - [ ] `social.coves.community.create` - **Handler exists**, needs E2E test with real PDS

     

       95
       -
       - [ ] `social.coves.community.get` - **Handler exists**, needs E2E test

     

       96
       -
       - [ ] `social.coves.community.update` - **Handler exists**, needs E2E test with community credentials

     

       97
       -
       - [ ] `social.coves.community.list` - **Handler exists**, needs E2E test with pagination

     

       98
       -
       - [ ] `social.coves.community.search` - **Handler exists**, needs E2E test with queries

     

       99
       -
       - [ ] `social.coves.community.subscribe` - **Handler exists**, needs E2E test

     

       100
       -
       - [ ] `social.coves.community.unsubscribe` - **Handler exists**, needs E2E test

     

       101
        
       

     

       102
       -
       **What's needed:**

     

       103
       -
       - E2E tests that verify complete flow: HTTP → Service → PDS → Firehose → Consumer → DB → HTTP response

     

       104
       -
       - Test with real PDS instance (not mocked)

     

       105
       -
       - Verify Jetstream consumer picks up events in real-time

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       106
        
       

     

       107
        
       ### Posts in Communities

     

       108
        
       **Status:** Lexicon designed, implementation TODO

     

       0
        
       
     

       109
        
       

     

       110
       -
       - [ ] Extend `social.coves.post` lexicon with `community` field

     

       111
       -
       - [ ] Create post endpoint (with community membership validation?)

     

       112
        
       - [ ] Feed generation for community posts

     

       113
        
       - [ ] Post consumer (index community posts from firehose)

     

       114
        
       - [ ] Community post count tracking

     

       0
        
       
     

       115
        
       

     

       116
       -
       **What's needed:**

     

       117
       -
       - Decide membership requirements for posting

     

       118
       -
       - Design feed generation algorithm

     

       119
       -
       - Implement post indexing in consumer

     

       120
       -
       - Add tests for post creation/listing

     

       121
        
       

     

       122
        
       ---

     

       123
        
       

     

       124
       -
       ## ⏳ TODO Before V1 Production Launch

     

       125
        
       

     

       126
       -
       ### Critical Security & Authorization

     

       127
       -
       - [ ] **OAuth Middleware:** Protect create/update/delete endpoints

     

       128
       -
       - [ ] **Authorization Checks:** Verify user is community creator/moderator

     

       129
       -
       - [ ] **Rate Limiting:** Prevent community creation spam (e.g., 5 per user per hour)

     

       130
       -
       - [ ] **Handle Collision Detection:** Prevent duplicate community handles

     

       131
       -
       - [ ] **DID Validation:** Verify DIDs before accepting create requests

     

       132
       -
       - [ ] **Token Refresh Logic:** Handle expired PDS access tokens

     

       0
        
       
     

       0
        
       
     

       133
        
       

     

       134
       -
       ### Community Discovery & Visibility

     

       135
       -
       - [ ] **Visibility Enforcement:** Respect public/unlisted/private settings in listings

     

       136
       -
       - [ ] **Federation Config:** Honor `allowExternalDiscovery` flag

     

       137
       -
       - [ ] **Search Relevance:** Implement ranking algorithm (members, activity, etc.)

     

       138
       -
       - [ ] **Directory Endpoint:** Public community directory with filters

     

       0
        
       
     

       139
        
       

     

       140
       -
       ### Membership & Participation

     

       141
       -
       - [ ] **Membership Tracking:** Auto-create membership on first post

     

       142
       -
       - [ ] **Reputation System:** Track user participation per community

     

       143
       -
       - [ ] **Subscription → Membership Flow:** Define conversion logic

     

       144
       -
       - [ ] **Member Lists:** Endpoint to list community members

     

       145
       -
       - [ ] **Moderator Assignment:** Allow creators to add moderators

     

       146
        
       

     

       147
       -
       ### Moderation (Basic)

     

       148
        
       - [ ] **Delist Community:** Remove from search/directory

     

       149
        
       - [ ] **Quarantine Community:** Show warning label

     

       150
        
       - [ ] **Remove Community:** Hide from instance AppView

     

       151
        
       - [ ] **Moderation Audit Log:** Track all moderation actions

     

       152
       -
       - [ ] **Admin Endpoints:** Instance operator tools

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       153
        
       

     

       154
        
       ### Token Refresh & Resilience

     

       155
       -
       - [ ] **Refresh Token Logic:** Auto-refresh expired PDS access tokens

     

       156
        
       - [ ] **Retry Mechanism:** Retry failed PDS calls with backoff

     

       157
        
       - [ ] **Credential Rotation:** Periodic password rotation for security

     

       158
        
       - [ ] **Error Recovery:** Graceful degradation if PDS is unavailable

···

       89
        
       ## 🚧 In Progress / Needs Testing

     

       90
        
       

     

       91
        
       ### XRPC API Endpoints

     

       92
       +
       **Status:** All core endpoints E2E tested! ✅

     

       93
       +
       

     

       94
       +
       **✅ E2E Tested (via community_e2e_test.go):**

     

       95
       +
       - [x] `social.coves.community.create` - Full E2E test with real PDS

     

       96
       +
       - [x] `social.coves.community.get` - E2E test validates HTTP endpoint

     

       97
       +
       - [x] `social.coves.community.list` - E2E test with pagination/filtering

     

       98
       +
       - [x] `social.coves.community.update` - E2E test verifies write-forward + PDS update

     

       99
       +
       - [x] `social.coves.community.subscribe` - E2E test verifies subscription in user's repo

     

       100
       +
       - [x] `social.coves.community.unsubscribe` - E2E test verifies PDS deletion

     

       101
       +
       

     

       102
       +
       **📍 Post-Alpha:**

     

       103
       +
       - [ ] `social.coves.community.search` - Handler exists, defer E2E testing to post-alpha

     

       104
       +
       

     

       105
       +
       **⚠️ Remaining Alpha Blocker:**

     

       106
       +
       - Replace placeholder auth (X-User-DID header) with OAuth context extraction across all endpoints

     

       107
        
       

     

       108
       +
       ---

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       109
        
       

     

       110
       +
       ## ⚠️ Alpha Blockers (Must Complete Before Alpha Launch)

     

       111
       +
       

     

       112
       +
       ### Critical Missing Features

     

       113
       +
       - [ ] **Subscription Visibility Level (1-5 Scale):** Implement feed slider from DOMAIN_KNOWLEDGE.md

     

       114
       +
         - Lexicon: ✅ Ready ([subscription.json:28-34](internal/atproto/lexicon/social/coves/actor/subscription.json))

     

       115
       +
         - Service: ❌ Not using `contentVisibility` field

     

       116
       +
         - Handler: ❌ Subscribe endpoint doesn't accept/store visibility level

     

       117
       +
         - **Impact:** Users can't control how much content they see from each community

     

       118
       +
       

     

       119
       +
       - [ ] **Community Blocking:** Users can block communities from their feeds

     

       120
       +
         - Lexicon: ❌ Need new record type (extend `social.coves.actor.block` or create new)

     

       121
       +
         - Service: ❌ No implementation (`BlockCommunity()` / `UnblockCommunity()`)

     

       122
       +
         - Handler: ❌ No endpoints

     

       123
       +
         - Repository: ❌ No methods

     

       124
       +
         - **Impact:** Users have no way to hide unwanted communities

     

       125
       +
       

     

       126
       +
       ### Critical Security (High Priority)

     

       127
       +
       - [ ] **OAuth Authentication:** Replace placeholder `X-User-DID` header with OAuth context

     

       128
       +
         - **Currently affected endpoints:** create, update, subscribe, unsubscribe

     

       129
       +
         - **See:** [PRD_BACKLOG.md P1 Priority](docs/PRD_BACKLOG.md#L42-L50)

     

       130
       +
       

     

       131
       +
       - [ ] **Token Refresh Logic:** Auto-refresh expired PDS access tokens

     

       132
       +
         - **Impact:** Communities break after ~2 hours when tokens expire

     

       133
       +
         - **See:** [PRD_BACKLOG.md P1 Priority](docs/PRD_BACKLOG.md#L31-L38)

     

       134
       +
       

     

       135
       +
       ---

     

       136
       +
       

     

       137
       +
       ## 📍 Beta Features (High Priority - Post Alpha)

     

       138
        
       

     

       139
        
       ### Posts in Communities

     

       140
        
       **Status:** Lexicon designed, implementation TODO

     

       141
       +
       **Priority:** HIGHEST for Beta 1

     

       142
        
       

     

       143
       +
       - [ ] `social.coves.post` already has `community` field ✅

     

       144
       +
       - [ ] Create post endpoint (decide: membership validation?)

     

       145
        
       - [ ] Feed generation for community posts

     

       146
        
       - [ ] Post consumer (index community posts from firehose)

     

       147
        
       - [ ] Community post count tracking

     

       148
       +
       - [ ] Decide membership requirements for posting

     

       149
        
       

     

       150
       +
       **Without posts, communities exist but can't be used!**

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       151
        
       

     

       152
        
       ---

     

       153
        
       

     

       154
       +
       ## 📍 Beta Features (Lower Priority)

     

       155
        
       

     

       156
       +
       ### Membership System

     

       157
       +
       **Status:** Lexicon exists, design decisions needed

     

       158
       +
       **Deferred:** Answer design questions before implementing

     

       159
       +
       

     

       160
       +
       - [ ] Decide: Auto-join on first post vs explicit join?

     

       161
       +
       - [ ] Decide: Reputation tracking in lexicon vs AppView only?

     

       162
       +
       - [ ] Implement membership record creation (if explicit join)

     

       163
       +
       - [ ] Member lists endpoint

     

       164
       +
       - [ ] Reputation tracking (if in lexicon)

     

       165
        
       

     

       166
       +
       ### Community Management

     

       167
       +
       - [ ] **Community Deletion:** Soft delete / permanent delete

     

       168
       +
       - [ ] **Wiki System:** Lexicon exists, no implementation

     

       169
       +
       - [ ] **Advanced Rules:** Separate rules records, moderation config

     

       170
       +
       - [ ] **Moderator Management:** Assign/remove moderators (governance work)

     

       171
       +
       - [ ] **Categories:** REMOVE from lexicon and code (not needed)

     

       172
        
       

     

       173
       +
       ### User Features

     

       174
       +
       - [ ] **Saved Items:** Save posts/comments for later

     

       175
       +
       - [ ] **User Flairs:** Per-community user flair (design TBD)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       176
        
       

     

       177
       +
       ### Instance Moderation

     

       178
        
       - [ ] **Delist Community:** Remove from search/directory

     

       179
        
       - [ ] **Quarantine Community:** Show warning label

     

       180
        
       - [ ] **Remove Community:** Hide from instance AppView

     

       181
        
       - [ ] **Moderation Audit Log:** Track all moderation actions

     

       182
       +
       

     

       183
       +
       ---

     

       184
       +
       

     

       185
       +
       ## ⏳ TODO Before V1 Production Launch

     

       186
       +
       

     

       187
       +
       ### Community Discovery & Visibility

     

       188
       +
       - [ ] **Visibility Enforcement:** Respect public/unlisted/private settings in listings

     

       189
       +
       - [ ] **Federation Config:** Honor `allowExternalDiscovery` flag

     

       190
       +
       - [ ] **Search Relevance:** Implement ranking algorithm (members, activity, etc.)

     

       191
       +
       - [ ] **Directory Endpoint:** Public community directory with filters

     

       192
       +
       - [ ] **Rate Limiting:** Prevent community creation spam (e.g., 5 per user per hour)

     

       193
       +
       - [ ] **Handle Collision Detection:** Prevent duplicate community handles

     

       194
       +
       - [ ] **DID Validation:** Verify DIDs before accepting create requests

     

       195
        
       

     

       196
        
       ### Token Refresh & Resilience

     

       0
        
       
     

       197
        
       - [ ] **Retry Mechanism:** Retry failed PDS calls with backoff

     

       198
        
       - [ ] **Credential Rotation:** Periodic password rotation for security

     

       199
        
       - [ ] **Error Recovery:** Graceful degradation if PDS is unavailable

+5 -3

docs/PRD_GOVERNANCE.md

···

       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

     

       0
        
       
     

       0
        
       
     

       23
        
       

     

       24
        
       **Key Issues:**

     

       25
        
       1. **Self-hosted instances:** Instance operator can't delegate community management to trusted users

···

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

     

       27
        
       1. **Self-hosted instances:** Instance operator can't delegate community management to trusted users