commit 12306aeb0b152b40f53256d99cdab8362f95608c · bretton.dev/coves

+29 -3

docs/PRD_COMMUNITIES.md

···

       171
       171
        
       - [ ] **Monitoring Guide:** Metrics and alerting setup

     

       172
       172
        
       - [ ] **Security Checklist:** Pre-launch security audit

     

       173
       173
        
       

     

       174
       174
       +
       ### Infrastructure & DNS

     

       175
       175
       +
       - [ ] **DNS Wildcard Setup:** Configure `*.communities.coves.social` for community handle resolution

     

       176
       176
       +
       - [ ] **Well-Known Endpoint:** Implement `.well-known/atproto-did` handler for `*.communities.coves.social` subdomains

     

       177
       177
       +
       

     

       174
       178
        
       ---

     

       175
       179
        
       

     

       176
       180
        
       ## Out of Scope (Future Versions)

     
···

       221
       225
        
       **Status:** ✅ Implemented and tested

     

       222
       226
        
       

     

       223
       227
        
       **Required Fields:**

     

       224
       224
       -
       - `handle` - Scoped handle (`!gaming@coves.social`)

     

       225
       225
       -
       - `atprotoHandle` - Real atProto handle (`gaming.communities.coves.social`)

     

       226
       226
       -
       - `name` - Community name

     

       228
       228
       +
       - `handle` - atProto handle (DNS-resolvable, e.g., `gaming.communities.coves.social`)

     

       229
       229
       +
       - `name` - Short community name for !mentions (e.g., `gaming`)

     

       227
       230
        
       - `createdBy` - DID of user who created community

     

       228
       231
        
       - `hostedBy` - DID of hosting instance

     

       229
       232
        
       - `visibility` - `"public"`, `"unlisted"`, or `"private"`

     

       230
       233
        
       - `federation.allowExternalDiscovery` - Boolean

     

       234
       234
       +
       

     

       235
       235
       +
       **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.

     

       231
       236
        
       

     

       232
       237
        
       **Optional Fields:**

     

       233
       238
        
       - `displayName` - Display name for UI

     
···

       276
       281
        
       ---

     

       277
       282
        
       

     

       278
       283
        
       ## Technical Decisions Log

     

       284
       284
       +
       

     

       285
       285
       +
       ### 2025-10-11: Single Handle Field (atProto-Compliant)

     

       286
       286
       +
       **Decision:** Use single `handle` field containing DNS-resolvable atProto handle; remove `atprotoHandle` field

     

       287
       287
       +
       

     

       288
       288
       +
       **Rationale:**

     

       289
       289
       +
       - Matches Bluesky pattern: `app.bsky.actor.profile` has one `handle` field

     

       290
       290
       +
       - Reduces confusion about which handle is "real"

     

       291
       291
       +
       - Simplifies lexicon (one field vs two)

     

       292
       292
       +
       - `!gaming@coves.social` display format is client-side UX concern, not protocol concern

     

       293
       293
       +
       - Follows separation of concerns: protocol layer uses DNS handles, UI layer formats for display

     

       294
       294
       +
       

     

       295
       295
       +
       **Implementation:**

     

       296
       296
       +
       - Lexicon: `handle` = `gaming.communities.coves.social` (DNS-resolvable)

     

       297
       297
       +
       - Client derives display: `!${name}@${instance}` from `name` + parsed instance

     

       298
       298
       +
       - Rich text facets can encode community mentions with `!` prefix for UX

     

       299
       299
       +
       

     

       300
       300
       +
       **Trade-offs Accepted:**

     

       301
       301
       +
       - Clients must parse/format for display (but already do this for `@user` mentions)

     

       302
       302
       +
       - No explicit "display handle" in record (but `displayName` serves this purpose)

     

       303
       303
       +
       

     

       304
       304
       +
       ---

     

       279
       305
        
       

     

       280
       306
        
       ### 2025-10-10: V2 Architecture Completed

     

       281
       307
        
       - Migrated from instance-owned to community-owned repositories

+31

docs/PRD_GOVERNANCE.md

···

       388
       388
        
       

     

       389
       389
        
       ## Technical Decisions Log

     

       390
       390
        
       

     

       391
       391
       +
       ### 2025-10-11: Moderator Records Storage Location

     

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

     

       393
       393
       +
       

     

       394
       394
       +
       **Rationale:**

     

       395
       395
       +
       1. **Federation security**: Community's PDS can write/delete records in its own repo without cross-PDS coordination

     

       396
       396
       +
       2. **Attack resistance**: Malicious self-hosted instances cannot forge or retain moderator status after revocation

     

       397
       397
       +
       3. **Single source of truth**: Community's repo is authoritative; no need to check multiple repos + revocation lists

     

       398
       398
       +
       4. **Instant revocation**: Deleting the record immediately removes moderator status across all instances

     

       399
       399
       +
       5. **Simpler implementation**: No invitation flow, no multi-step acceptance, no revocation reconciliation

     

       400
       400
       +
       

     

       401
       401
       +
       **Security Analysis:**

     

       402
       402
       +
       - **Option B (user's repo) vulnerability**: Attacker could self-host malicious AppView that ignores revocation signals stored in community's AppView database, presenting their moderator record as "proof" of authority

     

       403
       403
       +
       - **Option A (community's repo) security**: Even malicious instances must query community's PDS for authoritative moderator list; attacker cannot forge records in community's repository

     

       404
       404
       +
       

     

       405
       405
       +
       **Alternatives Considered:**

     

       406
       406
       +
       - **User's repo**: Follows atProto pattern for relationships (like `app.bsky.graph.follow`), provides user consent model, but introduces cross-instance write complexity and security vulnerabilities

     

       407
       407
       +
       - **Hybrid (both repos)**: Assignment in community's repo + acceptance in user's repo provides consent without compromising security, but significantly increases complexity

     

       408
       408
       +
       

     

       409
       409
       +
       **Trade-offs Accepted:**

     

       410
       410
       +
       - No explicit user consent (moderators are appointed, not invited)

     

       411
       411
       +
       - Users cannot easily query "what do I moderate?" without AppView index

     

       412
       412
       +
       - Doesn't follow standard atProto relationship pattern (but matches service account pattern like feed generators)

     

       413
       413
       +
       

     

       414
       414
       +
       **Implementation Notes:**

     

       415
       415
       +
       - Moderator records are source of truth for permissions

     

       416
       416
       +
       - AppView indexes these records from firehose for efficient querying

     

       417
       417
       +
       - User consent can be added later via optional acceptance records without changing security model

     

       418
       418
       +
       - Matches Bluesky's pattern: relationships in user's repo, service configuration in service's repo

     

       419
       419
       +
       

     

       420
       420
       +
       ---

     

       421
       421
       +
       

     

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

     

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

     

       393
       424