bretton.dev
+5
-4
.env.dev
+5
-4
.env.dev
·········
+33
-3
cmd/server/main.go
+33
-3
cmd/server/main.go
·········-communityService := communities.NewCommunityService(communityRepo, didGenerator, defaultPDS, instanceDID)+communityService := communities.NewCommunityService(communityRepo, didGenerator, defaultPDS, instanceDID, instanceDomain, provisioner)
+10
-6
docker-compose.dev.yml
+10
-6
docker-compose.dev.yml
······PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: ${PDS_PLC_ROTATION_KEY:-af514fb84c4356241deed29feb392d1ee359f99c05a7b8f7bff2e5f2614f64b2}+PDS_SERVICE_HANDLE_DOMAINS: ${PDS_SERVICE_HANDLE_DOMAINS:-.local.coves.dev,.communities.coves.social}·········
+159
docs/PRD_BACKLOG.md
+159
docs/PRD_BACKLOG.md
···+Miscellaneous platform improvements, bug fixes, and technical debt that don't fit into feature-specific PRDs.+**Problem:** Self-hosters can set `INSTANCE_DID=did:web:nintendo.com` without owning the domain, enabling domain impersonation attacks (e.g., `mario.communities.nintendo.com` on malicious instance).+**Solution:** Implement did:web verification per [atProto spec](https://atproto.com/specs/did-web) - fetch `https://domain/.well-known/did.json` on startup and verify it matches claimed DID. Add `SKIP_DID_WEB_VERIFICATION=true` for dev mode.+**Problem:** Community PDS access tokens expire (~2hrs). Updates fail until manual intervention.+**Solution:** Auto-refresh tokens before PDS operations. Parse JWT exp claim, use refresh token when expired, update DB.+**Problem:** Subscribe/unsubscribe and community creation need authenticated user DID. Currently using placeholder.+**Solution:** Extract authenticated DID from OAuth session context. Requires OAuth middleware integration.+**Code:** Multiple TODOs in [community/subscribe.go](../internal/api/handlers/community/subscribe.go#L46), [community/create.go](../internal/api/handlers/community/create.go#L38)+**Solution:** Enhance `InvalidHandleError` to explain root cause and suggest fixing `INSTANCE_DID`.+**Needed:** Document did:web setup, DNS config, secrets management, rate limiting, PostgreSQL hardening, monitoring.+**Code:** TODO in [jetstream/user_consumer.go:114](../internal/atproto/jetstream/user_consumer.go#L114)+Create `internal/config` package with structured config validation. Fail fast with clear errors.+Document: did:plc choice, pgcrypto encryption, Jetstream vs firehose, write-forward pattern, single handle field.+**Code:** TODO in [jetstream/user_consumer.go:203](../internal/atproto/jetstream/user_consumer.go#L203)+Changed default `INSTANCE_DID` from `did:web:coves.local` → `did:web:coves.social`. Fixed community creation failure due to disallowed `.local` TLD.
+240
-663
docs/PRD_COMMUNITIES.md
+240
-663
docs/PRD_COMMUNITIES.md
···-Coves communities are federated, instance-scoped forums built on atProto. Each community is identified by a scoped handle (`!gaming@coves.social`) and owned by a DID, enabling future portability and community governance.+Coves communities are federated, instance-scoped forums built on atProto. Each community is identified by a scoped handle (`!gaming@coves.social`) and owns its own atProto repository, enabling true portability and decentralized governance.-2. **DID-based ownership:** Communities are owned by DIDs (initially instance, eventually community)-3. **Web DID compatible:** Communities can use `did:web` for custom domains (e.g., `!photography@lens.club`)-- **Fragmentation handled socially:** Community governance and moderation quality drives membership+- [ ] `social.coves.community.update` - **Handler exists**, needs E2E test with community credentials+- E2E tests that verify complete flow: HTTP → Service → PDS → Firehose → Consumer → DB → HTTP response+- [ ] **DNS Wildcard Setup:** Configure `*.communities.coves.social` for community handle resolution+- [ ] **Well-Known Endpoint:** Implement `.well-known/atproto-did` handler for `*.communities.coves.social` subdomains-1. **Keypair Management**: Coves can manage community keypairs (like Bluesky manages user keys)+**Note:** The `!gaming@coves.social` format is derived client-side from `name` + instance for UI display. The `handle` field contains only the DNS-resolvable atProto handle.+**Decision:** Use single `handle` field containing DNS-resolvable atProto handle; remove `atprotoHandle` field+- Follows separation of concerns: protocol layer uses DNS handles, UI layer formats for display
+458
docs/PRD_GOVERNANCE.md
+458
docs/PRD_GOVERNANCE.md
···+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.+3. **User experience** - Clear, understandable permissions that work for self-hosted and centralized deployments+1. **Self-hosted instances:** Instance operator can't delegate community management to trusted users+- As a **self-hosted instance owner**, I want to create communities and assign moderators so I don't have to manage everything myself+Communities can be co-owned by multiple entities (users, instances, DAOs) with different ownership stakes:+- **Recommendation:** AppView DB initially (faster), add repository sync in Phase 2 for portability+- **Recommendation:** Instance admin emergency transfer after X months inactivity (define in Phase 2)+3. **Emergency override:** Can instance still moderate if community votes for illegal content?+4. **Governance defaults:** What happens to communities that don't explicitly configure governance?+- [ ] Creator → Moderator permission model understandable to users (< 5% support tickets about roles)+**Decision:** Store moderator records in community's repository (`at://community_did/social.coves.community.moderator/{tid}`), not user's repository+1. **Federation security**: Community's PDS can write/delete records in its own repo without cross-PDS coordination+2. **Attack resistance**: Malicious self-hosted instances cannot forge or retain moderator status after revocation+3. **Single source of truth**: Community's repo is authoritative; no need to check multiple repos + revocation lists+4. **Instant revocation**: Deleting the record immediately removes moderator status across all instances+5. **Simpler implementation**: No invitation flow, no multi-step acceptance, no revocation reconciliation+- **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+- **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+- Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)+- 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+- [PRD_COMMUNITIES.md](PRD_COMMUNITIES.md) - Core community architecture and V2 implementation
+4
-1
internal/api/handlers/community/errors.go
+4
-1
internal/api/handlers/community/errors.go
······writeError(w, http.StatusInternalServerError, "InternalServerError", "An internal error occurred")
+47
-29
internal/atproto/jetstream/community_consumer.go
+47
-29
internal/atproto/jetstream/community_consumer.go
···+return fmt.Errorf("invalid community profile rkey: expected 'self', got '%s' (V1 communities not supported)", commit.RKey)···+return fmt.Errorf("invalid community profile rkey: expected 'self', got '%s' (V1 communities not supported)", commit.RKey)···+AtprotoHandle string `json:"atprotoHandle"` // Real atProto handle (gaming.communities.coves.social)
+8
-1
internal/core/communities/community.go
+8
-1
internal/core/communities/community.go
···CreatedByDID string `json:"createdByDid" db:"created_by_did"` // User who created the community
+142
internal/core/communities/pds_provisioning.go
+142
internal/core/communities/pds_provisioning.go
···+func NewPDSAccountProvisioner(userService users.UserService, instanceDomain string, pdsURL string) *PDSAccountProvisioner {+email := fmt.Sprintf("community-%s@communities.%s", strings.ToLower(communityName), p.instanceDomain)
+142
-51
internal/core/communities/service.go
+142
-51
internal/core/communities/service.go
···-var communityHandleRegex = regexp.MustCompile(`^?@([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$`)+var communityHandleRegex = regexp.MustCompile(`^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$`)-func NewCommunityService(repo Repository, didGen *did.Generator, pdsURL string, instanceDID string) Service {+func NewCommunityService(repo Repository, didGen *did.Generator, pdsURL string, instanceDID string, instanceDomain string, provisioner *PDSAccountProvisioner) Service {···+// - Community owns its own repository (at://community_did/social.coves.community.profile/self)func (s *communityService) CreateCommunity(ctx context.Context, req CreateCommunityRequest) (*Community, error) {······-recordURI, recordCID, err := s.createRecordOnPDS(ctx, s.instanceDID, "social.coves.community.profile", "", profile)······-// Write-forward: update record on PDS using INSTANCE DID (communities are stored in instance repo)-recordURI, recordCID, err := s.putRecordOnPDS(ctx, s.instanceDID, "social.coves.community.profile", rkey, profile)···+func (s *communityService) createRecordOnPDSAs(ctx context.Context, repoDID, collection, rkey string, record map[string]interface{}, accessToken string) (string, string, error) {+endpoint := fmt.Sprintf("%s/xrpc/com.atproto.repo.createRecord", strings.TrimSuffix(s.pdsURL, "/"))func (s *communityService) putRecordOnPDS(ctx context.Context, repoDID, collection, rkey string, record map[string]interface{}) (string, string, error) {endpoint := fmt.Sprintf("%s/xrpc/com.atproto.repo.putRecord", strings.TrimSuffix(s.pdsURL, "/"))···+func (s *communityService) putRecordOnPDSAs(ctx context.Context, repoDID, collection, rkey string, record map[string]interface{}, accessToken string) (string, string, error) {+endpoint := fmt.Sprintf("%s/xrpc/com.atproto.repo.putRecord", strings.TrimSuffix(s.pdsURL, "/"))func (s *communityService) deleteRecordOnPDS(ctx context.Context, repoDID, collection, rkey string) error {endpoint := fmt.Sprintf("%s/xrpc/com.atproto.repo.deleteRecord", strings.TrimSuffix(s.pdsURL, "/"))···func (s *communityService) callPDS(ctx context.Context, method, endpoint string, payload map[string]interface{}) (string, string, error) {+// callPDSWithAuth makes a PDS call with a specific access token (V2: for community authentication)+func (s *communityService) callPDSWithAuth(ctx context.Context, method, endpoint string, payload map[string]interface{}, accessToken string) (string, string, error) {···
+21
-2
internal/db/migrations/005_create_communities_tables.sql
+21
-2
internal/db/migrations/005_create_communities_tables.sql
···visibility TEXT NOT NULL DEFAULT 'public' CHECK (visibility IN ('public', 'unlisted', 'private')),···CREATE INDEX idx_communities_name_trgm ON communities USING gin(name gin_trgm_ops); -- For fuzzy searchCREATE INDEX idx_communities_description_trgm ON communities USING gin(description gin_trgm_ops);+CREATE INDEX idx_communities_pds_email ON communities(pds_email); -- V2: For credential lookups+COMMENT ON COLUMN communities.pds_password_hash IS 'V2: bcrypt hash - NEVER return in API responses';+COMMENT ON COLUMN communities.pds_refresh_token IS 'V2: Refresh token - NEVER log or expose in APIs';···
+39
internal/db/migrations/006_encrypt_community_credentials.sql
+39
internal/db/migrations/006_encrypt_community_credentials.sql
···+CREATE INDEX idx_communities_encrypted_tokens ON communities(did) WHERE pds_access_token_encrypted IS NOT NULL;+COMMENT ON COLUMN communities.pds_access_token_encrypted IS 'Encrypted JWT - decrypt with pgp_sym_decrypt';+COMMENT ON COLUMN communities.pds_refresh_token_encrypted IS 'Encrypted refresh token - decrypt with pgp_sym_decrypt';
+29
-2
internal/db/postgres/community_repo.go
+29
-2
internal/db/postgres/community_repo.go
···+CASE WHEN $14 != '' THEN pgp_sym_encrypt($14, (SELECT encode(key_data, 'hex') FROM encryption_keys WHERE id = 1)) ELSE NULL END,+CASE WHEN $15 != '' THEN pgp_sym_encrypt($15, (SELECT encode(key_data, 'hex') FROM encryption_keys WHERE id = 1)) ELSE NULL END,······func (r *postgresCommunityRepo) GetByDID(ctx context.Context, did string) (*communities.Community, error) {+COALESCE(pgp_sym_decrypt(pds_access_token_encrypted, (SELECT encode(key_data, 'hex') FROM encryption_keys WHERE id = 1)), '') as pds_access_token,+COALESCE(pgp_sym_decrypt(pds_refresh_token_encrypted, (SELECT encode(key_data, 'hex') FROM encryption_keys WHERE id = 1)), '') as pds_refresh_token,·········
+283
tests/integration/community_credentials_test.go
+283
tests/integration/community_credentials_test.go
···+// TestCommunityRepository_CredentialPersistence tests that PDS credentials are properly persisted+t.Errorf("Decrypted access token mismatch: expected %s, got %s", accessToken, retrieved.PDSAccessToken)+t.Errorf("Decrypted refresh token mismatch: expected %s, got %s", refreshToken, retrieved.PDSRefreshToken)+specialToken := "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2NvdmVzLnNvY2lhbCIsInN1YiI6ImRpZDpwbGM6YWJjMTIzIiwiaWF0IjoxNzA5MjQwMDAwfQ.special/chars+here=="+t.Errorf("Special characters not preserved during encryption/decryption: expected %s, got %s", specialToken, retrieved.PDSAccessToken)+t.Errorf("V2 community should be self-owned: expected OwnerDID=%s, got %s", created.DID, created.OwnerDID)+t.Errorf("V2 community should be self-owned after retrieval: expected OwnerDID=%s, got %s", retrieved.DID, retrieved.OwnerDID)
+300
-61
tests/integration/community_e2e_test.go
+300
-61
tests/integration/community_e2e_test.go
·········-communityService := communities.NewCommunityService(communityRepo, didGen, pdsURL, instanceDID)+communityService := communities.NewCommunityService(communityRepo, didGen, pdsURL, instanceDID, instanceDomain, provisioner)······getRecordURL := fmt.Sprintf("%s/xrpc/com.atproto.repo.getRecord?repo=%s&collection=%s&rkey=%s",···+jetstreamURL := fmt.Sprintf("ws://%s:6008/subscribe?wantedCollections=social.coves.community.profile",+err := subscribeToJetstream(ctx, jetstreamURL, community.DID, consumer, eventChan, errorChan, done)············func createAndIndexCommunity(t *testing.T, service communities.Service, consumer *jetstream.CommunityEventConsumer, instanceDID string) *communities.Community {···+// communityTestIdentityResolver is a simple mock for testing (renamed to avoid conflict with oauth_test)+func (m *communityTestIdentityResolver) ResolveHandle(ctx context.Context, handle string) (string, string, error) {+func (m *communityTestIdentityResolver) ResolveDID(ctx context.Context, did string) (*identity.DIDDocument, error) {+func (m *communityTestIdentityResolver) Resolve(ctx context.Context, identifier string) (*identity.Identity, error) {+resp, err := http.Get(fmt.Sprintf("%s/xrpc/com.atproto.identity.resolveHandle?handle=%s", pdsURL, handle))
+285
tests/integration/community_v2_validation_test.go
+285
tests/integration/community_v2_validation_test.go
···+// TestCommunityConsumer_V2RKeyValidation tests that only V2 communities (rkey="self") are accepted+t.Errorf("V2 community should be self-owned: expected OwnerDID=%s, got %s", community.DID, community.OwnerDID)+if errMsg != "invalid community profile rkey: expected 'self', got '3k2j4h5g6f7d' (V1 communities not supported)" {+t.Errorf("V1 community should not have been indexed, expected ErrCommunityNotFound, got: %v", err)
+1
-3
tests/lexicon-test-data/community/profile-valid.json
+1
-3
tests/lexicon-test-data/community/profile-valid.json
···
+331
tests/unit/community_service_test.go
+331
tests/unit/community_service_test.go
···+func (m *mockCommunityRepo) Create(ctx context.Context, community *communities.Community) (*communities.Community, error) {+func (m *mockCommunityRepo) GetByDID(ctx context.Context, did string) (*communities.Community, error) {+func (m *mockCommunityRepo) GetByHandle(ctx context.Context, handle string) (*communities.Community, error) {+func (m *mockCommunityRepo) Update(ctx context.Context, community *communities.Community) (*communities.Community, error) {+func (m *mockCommunityRepo) List(ctx context.Context, req communities.ListCommunitiesRequest) ([]*communities.Community, int, error) {+func (m *mockCommunityRepo) Search(ctx context.Context, req communities.SearchCommunitiesRequest) ([]*communities.Community, int, error) {+func (m *mockCommunityRepo) Subscribe(ctx context.Context, subscription *communities.Subscription) (*communities.Subscription, error) {+func (m *mockCommunityRepo) SubscribeWithCount(ctx context.Context, subscription *communities.Subscription) (*communities.Subscription, error) {+func (m *mockCommunityRepo) Unsubscribe(ctx context.Context, userDID, communityDID string) error {+func (m *mockCommunityRepo) UnsubscribeWithCount(ctx context.Context, userDID, communityDID string) error {+func (m *mockCommunityRepo) GetSubscription(ctx context.Context, userDID, communityDID string) (*communities.Subscription, error) {+func (m *mockCommunityRepo) ListSubscriptions(ctx context.Context, userDID string, limit, offset int) ([]*communities.Subscription, error) {+func (m *mockCommunityRepo) ListSubscribers(ctx context.Context, communityDID string, limit, offset int) ([]*communities.Subscription, error) {+func (m *mockCommunityRepo) CreateMembership(ctx context.Context, membership *communities.Membership) (*communities.Membership, error) {+func (m *mockCommunityRepo) GetMembership(ctx context.Context, userDID, communityDID string) (*communities.Membership, error) {+func (m *mockCommunityRepo) UpdateMembership(ctx context.Context, membership *communities.Membership) (*communities.Membership, error) {+func (m *mockCommunityRepo) ListMembers(ctx context.Context, communityDID string, limit, offset int) ([]*communities.Membership, error) {+func (m *mockCommunityRepo) CreateModerationAction(ctx context.Context, action *communities.ModerationAction) (*communities.ModerationAction, error) {+func (m *mockCommunityRepo) ListModerationActions(ctx context.Context, communityDID string, limit, offset int) ([]*communities.ModerationAction, error) {+func (m *mockCommunityRepo) IncrementMemberCount(ctx context.Context, communityDID string) error {+func (m *mockCommunityRepo) DecrementMemberCount(ctx context.Context, communityDID string) error {+func (m *mockCommunityRepo) IncrementSubscriberCount(ctx context.Context, communityDID string) error {+func (m *mockCommunityRepo) DecrementSubscriberCount(ctx context.Context, communityDID string) error {+func (m *mockCommunityRepo) IncrementPostCount(ctx context.Context, communityDID string) error {+// TestCommunityService_UpdateWithCredentials tests that UpdateCommunity uses community credentials+w.Write([]byte(`{"uri":"at://did:plc:community/social.coves.community.profile/self","cid":"bafyrei456"}`))