comparing 8a168984b2d15bba3c102067fc968bdc436deb93 and feat/dpop-token-binding on bretton.dev/coves

+1 -1

scripts/generate_deep_thread.go

···

       84
       84
        
       

     

       85
       85
        
       func createComment(db *sql.DB, user *User, content, parentURI, parentCID string, createdAt time.Time) (*Comment, error) {

     

       86
       86
        
       	rkey := generateTID()

     

       87
       87
       -
       	uri := fmt.Sprintf("at://%s/social.coves.feed.comment/%s", user.DID, rkey)

     

       87
       87
       +
       	uri := fmt.Sprintf("at://%s/social.coves.community.comment/%s", user.DID, rkey)

     

       88
       88
        
       	cid := fmt.Sprintf("bafy%s", rkey)

     

       89
       89
        
       

     

       90
       90
        
       	comment := &Comment{

+1 -1

scripts/generate_nba_comments.go

···

       144
       144
        
       

     

       145
       145
        
       func createComment(db *sql.DB, user *User, content, parentURI, parentCID string, createdAt time.Time) (*Comment, error) {

     

       146
       146
        
       	rkey := generateTID()

     

       147
       147
       -
       	uri := fmt.Sprintf("at://%s/social.coves.feed.comment/%s", user.DID, rkey)

     

       147
       147
       +
       	uri := fmt.Sprintf("at://%s/social.coves.community.comment/%s", user.DID, rkey)

     

       148
       148
        
       	cid := fmt.Sprintf("bafy%s", rkey)

     

       149
       149
        
       

     

       150
       150
        
       	comment := &Comment{

+1 -1

scripts/generate_test_comments.go

···

       140
       140
        
       

     

       141
       141
        
       func createComment(db *sql.DB, user *User, content, parentURI, parentCID string, createdAt time.Time) (*Comment, error) {

     

       142
       142
        
       	rkey := generateTID()

     

       143
       143
       -
       	uri := fmt.Sprintf("at://%s/social.coves.feed.comment/%s", user.DID, rkey)

     

       143
       143
       +
       	uri := fmt.Sprintf("at://%s/social.coves.community.comment/%s", user.DID, rkey)

     

       144
       144
        
       	cid := fmt.Sprintf("bafy%s", rkey)

     

       145
       145
        
       

     

       146
       146
        
       	comment := &Comment{

+18 -15

docs/COMMENT_SYSTEM_IMPLEMENTATION.md

···

       308
       308
        
       ```json

     

       309
       309
        
       {

     

       310
       310
        
         "lexicon": 1,

     

       311
       311
       -
         "id": "social.coves.feed.comment",

     

       311
       311
       +
         "id": "social.coves.community.comment",

     

       312
       312
        
         "defs": {

     

       313
       313
        
           "main": {

     

       314
       314
        
             "type": "record",

     
···

       365
       365
        
       ```sql

     

       366
       366
        
       CREATE TABLE comments (

     

       367
       367
        
           id BIGSERIAL PRIMARY KEY,

     

       368
       368
       -
           uri TEXT UNIQUE NOT NULL,               -- AT-URI (at://commenter_did/social.coves.feed.comment/rkey)

     

       368
       368
       +
           uri TEXT UNIQUE NOT NULL,               -- AT-URI (at://commenter_did/social.coves.community.comment/rkey)

     

       369
       369
        
           cid TEXT NOT NULL,                      -- Content ID

     

       370
       370
        
           rkey TEXT NOT NULL,                     -- Record key (TID)

     

       371
       371
        
           commenter_did TEXT NOT NULL,            -- User who commented (from AT-URI repo field)

     
···

       559
       559
        
               return nil

     

       560
       560
        
           }

     

       561
       561
        
       

     

       562
       562
       -
           if event.Commit.Collection == "social.coves.feed.comment" {

     

       562
       562
       +
           if event.Commit.Collection == "social.coves.community.comment" {

     

       563
       563
        
               switch event.Commit.Operation {

     

       564
       564
        
               case "create":

     

       565
       565
        
                   return c.createComment(ctx, event.Did, commit)

     
···

       653
       653
        
       - Auto-reconnect on errors (5-second retry)

     

       654
       654
        
       - Ping/pong keepalive (30-second ping, 60-second read deadline)

     

       655
       655
        
       - Graceful shutdown via context cancellation

     

       656
       656
       -
       - Subscribes to: `wantedCollections=social.coves.feed.comment`

     

       656
       656
       +
       - Subscribes to: `wantedCollections=social.coves.community.comment`

     

       657
       657
        
       

     

       658
       658
        
       ---

     

       659
       659
        
       

     
···

       669
       669
        
       // Start Jetstream consumer for comments

     

       670
       670
        
       commentJetstreamURL := os.Getenv("COMMENT_JETSTREAM_URL")

     

       671
       671
        
       if commentJetstreamURL == "" {

     

       672
       672
       -
           commentJetstreamURL = "ws://localhost:6008/subscribe?wantedCollections=social.coves.feed.comment"

     

       672
       672
       +
           commentJetstreamURL = "ws://localhost:6008/subscribe?wantedCollections=social.coves.community.comment"

     

       673
       673
        
       }

     

       674
       674
        
       

     

       675
       675
        
       commentEventConsumer := jetstream.NewCommentEventConsumer(commentRepo, db)

     
···

       682
       682
        
       }()

     

       683
       683
        
       

     

       684
       684
        
       log.Printf("Started Jetstream comment consumer: %s", commentJetstreamURL)

     

       685
       685
       -
       log.Println("  - Indexing: social.coves.feed.comment CREATE/UPDATE/DELETE operations")

     

       685
       685
       +
       log.Println("  - Indexing: social.coves.community.comment CREATE/UPDATE/DELETE operations")

     

       686
       686
        
       log.Println("  - Updating: Post comment counts and comment reply counts atomically")

     

       687
       687
        
       ```

     

       688
       688
        
       

     
···

       835
       835
        
       | Aspect | Votes | Comments |

     

       836
       836
        
       |--------|-------|----------|

     

       837
       837
        
       | **Location** | User repositories | User repositories |

     

       838
       838
       -
       | **Lexicon** | `social.coves.feed.vote` | `social.coves.feed.comment` |

     

       838
       838
       +
       | **Lexicon** | `social.coves.feed.vote` | `social.coves.community.comment` |

     

       839
       839
        
       | **Operations** | CREATE, DELETE | CREATE, UPDATE, DELETE |

     

       840
       840
        
       | **Mutability** | Immutable | Editable |

     

       841
       841
        
       | **Foreign Keys** | None (out-of-order indexing) | None (out-of-order indexing) |

     
···

       1197
       1197
        
       

     

       1198
       1198
        
       ---

     

       1199
       1199
        
       

     

       1200
       1200
       -
       ### 📋 Phase 4: Namespace Migration (Separate Task)

     

       1200
       1200
       +
       ### ✅ Phase 4: Namespace Migration (COMPLETED)

     

       1201
       1201
       +
       

     

       1202
       1202
       +
       **Completed:** 2025-11-16

     

       1201
       1203
        
       

     

       1202
       1204
        
       **Scope:**

     

       1203
       1203
       -
       - Migrate existing `social.coves.feed.comment` records to `social.coves.community.comment`

     

       1204
       1204
       -
       - Update all AT-URIs in database

     

       1205
       1205
       -
       - Update Jetstream consumer collection filter

     

       1206
       1206
       -
       - Migration script with rollback capability

     

       1207
       1207
       -
       - Zero-downtime deployment strategy

     

       1205
       1205
       +
       - ✅ Migrated `social.coves.community.comment` namespace to `social.coves.community.comment`

     

       1206
       1206
       +
       - ✅ Updated lexicon definitions (record and query schemas)

     

       1207
       1207
       +
       - ✅ Updated Jetstream consumer collection filter

     

       1208
       1208
       +
       - ✅ Updated all code references (consumer, service, validation layers)

     

       1209
       1209
       +
       - ✅ Updated integration tests and test data generation scripts

     

       1210
       1210
       +
       - ✅ Created database migration (018_migrate_comment_namespace.sql)

     

       1208
       1211
        
       

     

       1209
       1209
       -
       **Note:** Currently out of scope - will be tackled separately when needed.

     

       1212
       1212
       +
       **Note:** Since we're pre-production, no historical data migration was needed. Migration script updates URIs in comments table (uri, root_uri, parent_uri columns).

     

       1210
       1213
        
       

     

       1211
       1214
        
       ---

     

       1212
       1215
        
       

     
···

       1456
       1459
        
       ### Environment Variables

     

       1457
       1460
        
       ```bash

     

       1458
       1461
        
       # Jetstream URL (optional, defaults to localhost:6008)

     

       1459
       1459
       -
       export COMMENT_JETSTREAM_URL="ws://localhost:6008/subscribe?wantedCollections=social.coves.feed.comment"

     

       1462
       1462
       +
       export COMMENT_JETSTREAM_URL="ws://localhost:6008/subscribe?wantedCollections=social.coves.community.comment"

     

       1460
       1463
        
       

     

       1461
       1464
        
       # Database URL

     

       1462
       1465
        
       export TEST_DATABASE_URL="postgres://test_user:test_password@localhost:5434/coves_test?sslmode=disable"

+3 -2

internal/core/unfurl/providers.go

···

       108
       108
        
       

     

       109
       109
        
       // normalizeURL converts protocol-relative URLs to HTTPS

     

       110
       110
        
       // Examples:

     

       111
       111
       -
       //   "//example.com/image.jpg" -> "https://example.com/image.jpg"

     

       112
       112
       -
       //   "https://example.com/image.jpg" -> "https://example.com/image.jpg" (unchanged)

     

       111
       111
       +
       //

     

       112
       112
       +
       //	"//example.com/image.jpg" -> "https://example.com/image.jpg"

     

       113
       113
       +
       //	"https://example.com/image.jpg" -> "https://example.com/image.jpg" (unchanged)

     

       113
       114
        
       func normalizeURL(urlStr string) string {

     

       114
       115
        
       	if strings.HasPrefix(urlStr, "//") {

     

       115
       116
        
       		return "https:" + urlStr

-1

internal/core/unfurl/providers_test.go

+785

docs/federation-prd.md

···

       1
       1
       +
       # Federation PRD: Cross-Instance Posting (Beta)

     

       2
       2
       +
       

     

       3
       3
       +
       **Status:** Planning - Beta

     

       4
       4
       +
       **Target:** Beta Release

     

       5
       5
       +
       **Owner:** TBD

     

       6
       6
       +
       **Last Updated:** 2025-11-16

     

       7
       7
       +
       

     

       8
       8
       +
       ---

     

       9
       9
       +
       

     

       10
       10
       +
       ## Overview

     

       11
       11
       +
       

     

       12
       12
       +
       Enable Lemmy-style federation where users on any Coves instance can post to communities hosted on other instances, while maintaining community ownership and moderation control.

     

       13
       13
       +
       

     

       14
       14
       +
       ### Problem Statement

     

       15
       15
       +
       

     

       16
       16
       +
       **Current (Alpha):**

     

       17
       17
       +
       - Posts to communities require community credentials

     

       18
       18
       +
       - Users can only post to communities on their home instance

     

       19
       19
       +
       - No true federation across instances

     

       20
       20
       +
       

     

       21
       21
       +
       **Desired (Beta):**

     

       22
       22
       +
       - User A@coves.social can post to !gaming@covesinstance.com

     

       23
       23
       +
       - Communities maintain full moderation control

     

       24
       24
       +
       - Content lives in community repositories (not user repos)

     

       25
       25
       +
       - Seamless UX - users don't think about federation

     

       26
       26
       +
       

     

       27
       27
       +
       ---

     

       28
       28
       +
       

     

       29
       29
       +
       ## Goals

     

       30
       30
       +
       

     

       31
       31
       +
       ### Primary Goals

     

       32
       32
       +
       1. **Enable cross-instance posting** - Users can post to any community on any federated instance

     

       33
       33
       +
       2. **Preserve community ownership** - Posts live in community repos, not user repos

     

       34
       34
       +
       3. **atProto-native implementation** - Use `com.atproto.server.getServiceAuth` pattern

     

       35
       35
       +
       4. **Maintain security** - No compromise on auth, validation, or moderation

     

       36
       36
       +
       

     

       37
       37
       +
       ### Non-Goals (Future Versions)

     

       38
       38
       +
       - Automatic instance discovery (Beta: manual allowlist)

     

       39
       39
       +
       - Cross-instance moderation delegation

     

       40
       40
       +
       - Content mirroring/replication

     

       41
       41
       +
       - User migration between instances

     

       42
       42
       +
       

     

       43
       43
       +
       ---

     

       44
       44
       +
       

     

       45
       45
       +
       ## Technical Approach

     

       46
       46
       +
       

     

       47
       47
       +
       ### Architecture: atProto Service Auth

     

       48
       48
       +
       

     

       49
       49
       +
       Use atProto's native service authentication delegation pattern:

     

       50
       50
       +
       

     

       51
       51
       +
       ```

     

       52
       52
       +
       ┌─────────────┐         ┌──────────────────┐         ┌─────────────┐

     

       53
       53
       +
       │  User A     │         │  coves.social    │         │ covesinstance│

     

       54
       54
       +
       │ @coves.soc  │────────▶│   AppView        │────────▶│  .com PDS   │

     

       55
       55
       +
       └─────────────┘  (1)    └──────────────────┘  (2)    └─────────────┘

     

       56
       56
       +
                       JWT auth    Request Service Auth         Validate

     

       57
       57
       +
                                            │                       │

     

       58
       58
       +
                                            │◀──────────────────────┘

     

       59
       59
       +
                                            │        (3) Scoped Token

     

       60
       60
       +
                                            │

     

       61
       61
       +
                                            ▼

     

       62
       62
       +
                                   ┌──────────────────┐

     

       63
       63
       +
                                   │ covesinstance    │

     

       64
       64
       +
                                   │  .com PDS        │

     

       65
       65
       +
                                   │ Write Post       │

     

       66
       66
       +
                                   └──────────────────┘

     

       67
       67
       +
                                            │

     

       68
       68
       +
                                            ▼

     

       69
       69
       +
                                   ┌──────────────────┐

     

       70
       70
       +
                                   │   Firehose       │

     

       71
       71
       +
                                   │  (broadcasts)    │

     

       72
       72
       +
                                   └──────────────────┘

     

       73
       73
       +
                                            │

     

       74
       74
       +
                               ┌────────────┴────────────┐

     

       75
       75
       +
                               ▼                         ▼

     

       76
       76
       +
                       ┌──────────────┐        ┌──────────────┐

     

       77
       77
       +
                       │ coves.social │        │covesinstance │

     

       78
       78
       +
                       │   AppView    │        │  .com AppView│

     

       79
       79
       +
                       │  (indexes)   │        │   (indexes)  │

     

       80
       80
       +
                       └──────────────┘        └──────────────┘

     

       81
       81
       +
       ```

     

       82
       82
       +
       

     

       83
       83
       +
       ### Flow Breakdown

     

       84
       84
       +
       

     

       85
       85
       +
       **Step 1: User Authentication (Unchanged)**

     

       86
       86
       +
       - User authenticates with their home instance (coves.social)

     

       87
       87
       +
       - Receives JWT token for API requests

     

       88
       88
       +
       

     

       89
       89
       +
       **Step 2: Service Auth Request (New)**

     

       90
       90
       +
       - When posting to remote community, AppView requests service auth token

     

       91
       91
       +
       - Endpoint: `POST {remote-pds}/xrpc/com.atproto.server.getServiceAuth`

     

       92
       92
       +
       - Payload:

     

       93
       93
       +
         ```json

     

       94
       94
       +
         {

     

       95
       95
       +
           "aud": "did:plc:community123",  // Community DID

     

       96
       96
       +
           "exp": 1234567890,               // Token expiration

     

       97
       97
       +
           "lxm": "social.coves.community.post.create"  // Authorized method

     

       98
       98
       +
         }

     

       99
       99
       +
         ```

     

       100
       100
       +
       

     

       101
       101
       +
       **Step 3: Service Auth Validation (New - PDS Side)**

     

       102
       102
       +
       - Remote PDS validates request:

     

       103
       103
       +
         - Is requesting service trusted? (instance allowlist)

     

       104
       104
       +
         - Is user banned from community?

     

       105
       105
       +
         - Does community allow remote posts?

     

       106
       106
       +
         - Rate limiting checks

     

       107
       107
       +
       - Returns scoped token valid for specific community + operation

     

       108
       108
       +
       

     

       109
       109
       +
       **Step 4: Post Creation (Modified)**

     

       110
       110
       +
       - AppView uses service auth token to write to remote PDS

     

       111
       111
       +
       - Same `com.atproto.repo.createRecord` endpoint as current implementation

     

       112
       112
       +
       - Post record written to community's repository

     

       113
       113
       +
       

     

       114
       114
       +
       **Step 5: Indexing (Unchanged)**

     

       115
       115
       +
       - PDS broadcasts to firehose

     

       116
       116
       +
       - All AppViews index via Jetstream consumers

     

       117
       117
       +
       

     

       118
       118
       +
       ---

     

       119
       119
       +
       

     

       120
       120
       +
       ## Implementation Details

     

       121
       121
       +
       

     

       122
       122
       +
       ### Phase 1: Service Detection (Local vs Remote)

     

       123
       123
       +
       

     

       124
       124
       +
       **File:** `internal/core/posts/service.go`

     

       125
       125
       +
       

     

       126
       126
       +
       ```go

     

       127
       127
       +
       func (s *postService) CreatePost(ctx context.Context, req CreatePostRequest) (*CreatePostResponse, error) {

     

       128
       128
       +
           // ... existing validation ...

     

       129
       129
       +
       

     

       130
       130
       +
           community, err := s.communityService.GetByDID(ctx, communityDID)

     

       131
       131
       +
           if err != nil {

     

       132
       132
       +
               return nil, err

     

       133
       133
       +
           }

     

       134
       134
       +
       

     

       135
       135
       +
           // NEW: Route based on community location

     

       136
       136
       +
           if s.isLocalCommunity(community) {

     

       137
       137
       +
               return s.createLocalPost(ctx, community, req)

     

       138
       138
       +
           }

     

       139
       139
       +
           return s.createFederatedPost(ctx, community, req)

     

       140
       140
       +
       }

     

       141
       141
       +
       

     

       142
       142
       +
       func (s *postService) isLocalCommunity(community *communities.Community) bool {

     

       143
       143
       +
           localPDSHost := extractHost(s.pdsURL)

     

       144
       144
       +
           communityPDSHost := extractHost(community.PDSURL)

     

       145
       145
       +
           return localPDSHost == communityPDSHost

     

       146
       146
       +
       }

     

       147
       147
       +
       ```

     

       148
       148
       +
       

     

       149
       149
       +
       ### Phase 2: Service Auth Client

     

       150
       150
       +
       

     

       151
       151
       +
       **New File:** `internal/atproto/service_auth/client.go`

     

       152
       152
       +
       

     

       153
       153
       +
       ```go

     

       154
       154
       +
       type ServiceAuthClient interface {

     

       155
       155
       +
           // RequestServiceAuth obtains a scoped token for writing to remote community

     

       156
       156
       +
           RequestServiceAuth(ctx context.Context, opts ServiceAuthOptions) (*ServiceAuthToken, error)

     

       157
       157
       +
       }

     

       158
       158
       +
       

     

       159
       159
       +
       type ServiceAuthOptions struct {

     

       160
       160
       +
           RemotePDSURL  string    // Remote PDS endpoint

     

       161
       161
       +
           CommunityDID  string    // Target community DID

     

       162
       162
       +
           UserDID       string    // Author DID (for validation)

     

       163
       163
       +
           Method        string    // "social.coves.community.post.create"

     

       164
       164
       +
           ExpiresIn     int       // Token lifetime (seconds)

     

       165
       165
       +
       }

     

       166
       166
       +
       

     

       167
       167
       +
       type ServiceAuthToken struct {

     

       168
       168
       +
           Token     string    // JWT token for auth

     

       169
       169
       +
           ExpiresAt time.Time // When token expires

     

       170
       170
       +
       }

     

       171
       171
       +
       

     

       172
       172
       +
       func (c *serviceAuthClient) RequestServiceAuth(ctx context.Context, opts ServiceAuthOptions) (*ServiceAuthToken, error) {

     

       173
       173
       +
           endpoint := fmt.Sprintf("%s/xrpc/com.atproto.server.getServiceAuth", opts.RemotePDSURL)

     

       174
       174
       +
       

     

       175
       175
       +
           payload := map[string]interface{}{

     

       176
       176
       +
               "aud": opts.CommunityDID,

     

       177
       177
       +
               "exp": time.Now().Add(time.Duration(opts.ExpiresIn) * time.Second).Unix(),

     

       178
       178
       +
               "lxm": opts.Method,

     

       179
       179
       +
           }

     

       180
       180
       +
       

     

       181
       181
       +
           // Sign request with our instance DID credentials

     

       182
       182
       +
           signedReq, err := c.signRequest(payload)

     

       183
       183
       +
           if err != nil {

     

       184
       184
       +
               return nil, fmt.Errorf("failed to sign service auth request: %w", err)

     

       185
       185
       +
           }

     

       186
       186
       +
       

     

       187
       187
       +
           resp, err := c.httpClient.Post(endpoint, signedReq)

     

       188
       188
       +
           if err != nil {

     

       189
       189
       +
               return nil, fmt.Errorf("service auth request failed: %w", err)

     

       190
       190
       +
           }

     

       191
       191
       +
       

     

       192
       192
       +
           return parseServiceAuthResponse(resp)

     

       193
       193
       +
       }

     

       194
       194
       +
       ```

     

       195
       195
       +
       

     

       196
       196
       +
       ### Phase 3: Federated Post Creation

     

       197
       197
       +
       

     

       198
       198
       +
       **File:** `internal/core/posts/service.go`

     

       199
       199
       +
       

     

       200
       200
       +
       ```go

     

       201
       201
       +
       func (s *postService) createFederatedPost(ctx context.Context, community *communities.Community, req CreatePostRequest) (*CreatePostResponse, error) {

     

       202
       202
       +
           // 1. Request service auth token from remote PDS

     

       203
       203
       +
           token, err := s.serviceAuthClient.RequestServiceAuth(ctx, service_auth.ServiceAuthOptions{

     

       204
       204
       +
               RemotePDSURL: community.PDSURL,

     

       205
       205
       +
               CommunityDID: community.DID,

     

       206
       206
       +
               UserDID:      req.AuthorDID,

     

       207
       207
       +
               Method:       "social.coves.community.post.create",

     

       208
       208
       +
               ExpiresIn:    300, // 5 minutes

     

       209
       209
       +
           })

     

       210
       210
       +
           if err != nil {

     

       211
       211
       +
               // Handle specific errors

     

       212
       212
       +
               if isUnauthorized(err) {

     

       213
       213
       +
                   return nil, ErrNotAuthorizedRemote

     

       214
       214
       +
               }

     

       215
       215
       +
               if isBanned(err) {

     

       216
       216
       +
                   return nil, ErrBannedRemote

     

       217
       217
       +
               }

     

       218
       218
       +
               return nil, fmt.Errorf("failed to obtain service auth: %w", err)

     

       219
       219
       +
           }

     

       220
       220
       +
       

     

       221
       221
       +
           // 2. Build post record (same as local)

     

       222
       222
       +
           postRecord := PostRecord{

     

       223
       223
       +
               Type:      "social.coves.community.post",

     

       224
       224
       +
               Community: community.DID,

     

       225
       225
       +
               Author:    req.AuthorDID,

     

       226
       226
       +
               Title:     req.Title,

     

       227
       227
       +
               Content:   req.Content,

     

       228
       228
       +
               // ... other fields ...

     

       229
       229
       +
               CreatedAt: time.Now().UTC().Format(time.RFC3339),

     

       230
       230
       +
           }

     

       231
       231
       +
       

     

       232
       232
       +
           // 3. Write to remote PDS using service auth token

     

       233
       233
       +
           uri, cid, err := s.createPostOnRemotePDS(ctx, community.PDSURL, community.DID, postRecord, token.Token)

     

       234
       234
       +
           if err != nil {

     

       235
       235
       +
               return nil, fmt.Errorf("failed to write to remote PDS: %w", err)

     

       236
       236
       +
           }

     

       237
       237
       +
       

     

       238
       238
       +
           log.Printf("[FEDERATION] User %s posted to remote community %s: %s",

     

       239
       239
       +
               req.AuthorDID, community.DID, uri)

     

       240
       240
       +
       

     

       241
       241
       +
           return &CreatePostResponse{

     

       242
       242
       +
               URI: uri,

     

       243
       243
       +
               CID: cid,

     

       244
       244
       +
           }, nil

     

       245
       245
       +
       }

     

       246
       246
       +
       

     

       247
       247
       +
       func (s *postService) createPostOnRemotePDS(

     

       248
       248
       +
           ctx context.Context,

     

       249
       249
       +
           pdsURL string,

     

       250
       250
       +
           communityDID string,

     

       251
       251
       +
           record PostRecord,

     

       252
       252
       +
           serviceAuthToken string,

     

       253
       253
       +
       ) (uri, cid string, err error) {

     

       254
       254
       +
           endpoint := fmt.Sprintf("%s/xrpc/com.atproto.repo.createRecord", pdsURL)

     

       255
       255
       +
       

     

       256
       256
       +
           payload := map[string]interface{}{

     

       257
       257
       +
               "repo":       communityDID,

     

       258
       258
       +
               "collection": "social.coves.community.post",

     

       259
       259
       +
               "record":     record,

     

       260
       260
       +
           }

     

       261
       261
       +
       

     

       262
       262
       +
           jsonData, _ := json.Marshal(payload)

     

       263
       263
       +
           req, _ := http.NewRequestWithContext(ctx, "POST", endpoint, bytes.NewBuffer(jsonData))

     

       264
       264
       +
       

     

       265
       265
       +
           // Use service auth token instead of community credentials

     

       266
       266
       +
           req.Header.Set("Authorization", "Bearer "+serviceAuthToken)

     

       267
       267
       +
           req.Header.Set("Content-Type", "application/json")

     

       268
       268
       +
       

     

       269
       269
       +
           // ... execute request, parse response ...

     

       270
       270
       +
           return uri, cid, nil

     

       271
       271
       +
       }

     

       272
       272
       +
       ```

     

       273
       273
       +
       

     

       274
       274
       +
       ### Phase 4: PDS Service Auth Validation (PDS Extension)

     

       275
       275
       +
       

     

       276
       276
       +
       **Note:** This requires extending the PDS. Options:

     

       277
       277
       +
       1. Contribute to official atproto PDS

     

       278
       278
       +
       2. Run modified PDS fork

     

       279
       279
       +
       3. Use PDS middleware/proxy

     

       280
       280
       +
       

     

       281
       281
       +
       **Conceptual Implementation:**

     

       282
       282
       +
       

     

       283
       283
       +
       ```go

     

       284
       284
       +
       // PDS validates service auth requests before issuing tokens

     

       285
       285
       +
       func (h *ServiceAuthHandler) HandleGetServiceAuth(w http.ResponseWriter, r *http.Request) {

     

       286
       286
       +
           var req ServiceAuthRequest

     

       287
       287
       +
           json.NewDecoder(r.Body).Decode(&req)

     

       288
       288
       +
       

     

       289
       289
       +
           // 1. Verify requesting service is trusted

     

       290
       290
       +
           requestingDID := extractDIDFromJWT(r.Header.Get("Authorization"))

     

       291
       291
       +
           if !h.isTrustedInstance(requestingDID) {

     

       292
       292
       +
               writeError(w, http.StatusForbidden, "UntrustedInstance", "Instance not in allowlist")

     

       293
       293
       +
               return

     

       294
       294
       +
           }

     

       295
       295
       +
       

     

       296
       296
       +
           // 2. Validate community exists on this PDS

     

       297
       297
       +
           community, err := h.getCommunityByDID(req.Aud)

     

       298
       298
       +
           if err != nil {

     

       299
       299
       +
               writeError(w, http.StatusNotFound, "CommunityNotFound", "Community not hosted here")

     

       300
       300
       +
               return

     

       301
       301
       +
           }

     

       302
       302
       +
       

     

       303
       303
       +
           // 3. Check user not banned (query from AppView or local moderation records)

     

       304
       304
       +
           if h.isUserBanned(req.UserDID, req.Aud) {

     

       305
       305
       +
               writeError(w, http.StatusForbidden, "Banned", "User banned from community")

     

       306
       306
       +
               return

     

       307
       307
       +
           }

     

       308
       308
       +
       

     

       309
       309
       +
           // 4. Check community settings (allows remote posts?)

     

       310
       310
       +
           if !community.AllowFederatedPosts {

     

       311
       311
       +
               writeError(w, http.StatusForbidden, "FederationDisabled", "Community doesn't accept federated posts")

     

       312
       312
       +
               return

     

       313
       313
       +
           }

     

       314
       314
       +
       

     

       315
       315
       +
           // 5. Rate limiting (per user, per community, per instance)

     

       316
       316
       +
           if h.exceedsRateLimit(req.UserDID, req.Aud, requestingDID) {

     

       317
       317
       +
               writeError(w, http.StatusTooManyRequests, "RateLimited", "Too many requests")

     

       318
       318
       +
               return

     

       319
       319
       +
           }

     

       320
       320
       +
       

     

       321
       321
       +
           // 6. Generate scoped token

     

       322
       322
       +
           token := h.issueServiceAuthToken(ServiceAuthTokenOptions{

     

       323
       323
       +
               Audience:    req.Aud,           // Community DID

     

       324
       324
       +
               Subject:     requestingDID,     // Requesting instance DID

     

       325
       325
       +
               Method:      req.Lxm,           // Authorized method

     

       326
       326
       +
               ExpiresAt:   time.Unix(req.Exp, 0),

     

       327
       327
       +
               Scopes:      []string{"write:posts"},

     

       328
       328
       +
           })

     

       329
       329
       +
       

     

       330
       330
       +
           json.NewEncoder(w).Encode(map[string]string{

     

       331
       331
       +
               "token": token,

     

       332
       332
       +
           })

     

       333
       333
       +
       }

     

       334
       334
       +
       ```

     

       335
       335
       +
       

     

       336
       336
       +
       ---

     

       337
       337
       +
       

     

       338
       338
       +
       ## Database Schema Changes

     

       339
       339
       +
       

     

       340
       340
       +
       ### New Table: `instance_federation`

     

       341
       341
       +
       

     

       342
       342
       +
       Tracks trusted instances and federation settings:

     

       343
       343
       +
       

     

       344
       344
       +
       ```sql

     

       345
       345
       +
       CREATE TABLE instance_federation (

     

       346
       346
       +
           id SERIAL PRIMARY KEY,

     

       347
       347
       +
           instance_did TEXT NOT NULL UNIQUE,

     

       348
       348
       +
           instance_domain TEXT NOT NULL,

     

       349
       349
       +
           trust_level TEXT NOT NULL,  -- 'trusted', 'limited', 'blocked'

     

       350
       350
       +
           allowed_methods TEXT[] NOT NULL DEFAULT '{}',

     

       351
       351
       +
           rate_limit_posts_per_hour INTEGER NOT NULL DEFAULT 100,

     

       352
       352
       +
           created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

     

       353
       353
       +
           updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

     

       354
       354
       +
           notes TEXT

     

       355
       355
       +
       );

     

       356
       356
       +
       

     

       357
       357
       +
       CREATE INDEX idx_instance_federation_did ON instance_federation(instance_did);

     

       358
       358
       +
       CREATE INDEX idx_instance_federation_trust ON instance_federation(trust_level);

     

       359
       359
       +
       ```

     

       360
       360
       +
       

     

       361
       361
       +
       ### New Table: `federation_rate_limits`

     

       362
       362
       +
       

     

       363
       363
       +
       Track federated post rate limits:

     

       364
       364
       +
       

     

       365
       365
       +
       ```sql

     

       366
       366
       +
       CREATE TABLE federation_rate_limits (

     

       367
       367
       +
           id SERIAL PRIMARY KEY,

     

       368
       368
       +
           user_did TEXT NOT NULL,

     

       369
       369
       +
           community_did TEXT NOT NULL,

     

       370
       370
       +
           instance_did TEXT NOT NULL,

     

       371
       371
       +
           window_start TIMESTAMPTZ NOT NULL,

     

       372
       372
       +
           post_count INTEGER NOT NULL DEFAULT 1,

     

       373
       373
       +
           created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

     

       374
       374
       +
           updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

     

       375
       375
       +
       

     

       376
       376
       +
           UNIQUE(user_did, community_did, instance_did, window_start)

     

       377
       377
       +
       );

     

       378
       378
       +
       

     

       379
       379
       +
       CREATE INDEX idx_federation_rate_limits_lookup

     

       380
       380
       +
           ON federation_rate_limits(user_did, community_did, instance_did, window_start);

     

       381
       381
       +
       ```

     

       382
       382
       +
       

     

       383
       383
       +
       ### Update Table: `communities`

     

       384
       384
       +
       

     

       385
       385
       +
       Add federation settings:

     

       386
       386
       +
       

     

       387
       387
       +
       ```sql

     

       388
       388
       +
       ALTER TABLE communities

     

       389
       389
       +
       ADD COLUMN allow_federated_posts BOOLEAN NOT NULL DEFAULT true,

     

       390
       390
       +
       ADD COLUMN federation_mode TEXT NOT NULL DEFAULT 'open';

     

       391
       391
       +
       -- federation_mode: 'open' (any instance), 'allowlist' (trusted only), 'local' (no federation)

     

       392
       392
       +
       ```

     

       393
       393
       +
       

     

       394
       394
       +
       ---

     

       395
       395
       +
       

     

       396
       396
       +
       ## Security Considerations

     

       397
       397
       +
       

     

       398
       398
       +
       ### 1. Instance Trust Model

     

       399
       399
       +
       

     

       400
       400
       +
       **Allowlist Approach (Beta):**

     

       401
       401
       +
       - Manual approval of federated instances

     

       402
       402
       +
       - Admin UI to manage instance trust levels

     

       403
       403
       +
       - Default: block all, explicit allow

     

       404
       404
       +
       

     

       405
       405
       +
       **Trust Levels:**

     

       406
       406
       +
       - `trusted` - Full federation, normal rate limits

     

       407
       407
       +
       - `limited` - Federation allowed, strict rate limits

     

       408
       408
       +
       - `blocked` - No federation

     

       409
       409
       +
       

     

       410
       410
       +
       ### 2. User Ban Synchronization

     

       411
       411
       +
       

     

       412
       412
       +
       **Challenge:** Remote instance needs to check local bans

     

       413
       413
       +
       

     

       414
       414
       +
       **Options:**

     

       415
       415
       +
       1. **Service auth validation** - PDS queries AppView for ban status

     

       416
       416
       +
       2. **Ban records in PDS** - Moderation records stored in community repo

     

       417
       417
       +
       3. **Cached ban list** - Remote instances cache ban lists (with TTL)

     

       418
       418
       +
       

     

       419
       419
       +
       **Beta Approach:** Option 1 (service auth validation queries AppView)

     

       420
       420
       +
       

     

       421
       421
       +
       ### 3. Rate Limiting

     

       422
       422
       +
       

     

       423
       423
       +
       **Multi-level rate limits:**

     

       424
       424
       +
       - Per user per community: 10 posts/hour

     

       425
       425
       +
       - Per instance per community: 100 posts/hour

     

       426
       426
       +
       - Per user across all communities: 50 posts/hour

     

       427
       427
       +
       

     

       428
       428
       +
       **Implementation:** In-memory + PostgreSQL for persistence

     

       429
       429
       +
       

     

       430
       430
       +
       ### 4. Content Validation

     

       431
       431
       +
       

     

       432
       432
       +
       **Same validation as local posts:**

     

       433
       433
       +
       - Lexicon validation

     

       434
       434
       +
       - Content length limits

     

       435
       435
       +
       - Embed validation

     

       436
       436
       +
       - Label validation

     

       437
       437
       +
       

     

       438
       438
       +
       **Additional federation checks:**

     

       439
       439
       +
       - Verify author DID is valid

     

       440
       440
       +
       - Verify requesting instance signature

     

       441
       441
       +
       - Verify token scopes match operation

     

       442
       442
       +
       

     

       443
       443
       +
       ---

     

       444
       444
       +
       

     

       445
       445
       +
       ## API Changes

     

       446
       446
       +
       

     

       447
       447
       +
       ### New Endpoint: `social.coves.federation.getTrustedInstances`

     

       448
       448
       +
       

     

       449
       449
       +
       **Purpose:** List instances this instance federates with

     

       450
       450
       +
       

     

       451
       451
       +
       **Lexicon:**

     

       452
       452
       +
       ```json

     

       453
       453
       +
       {

     

       454
       454
       +
         "lexicon": 1,

     

       455
       455
       +
         "id": "social.coves.federation.getTrustedInstances",

     

       456
       456
       +
         "defs": {

     

       457
       457
       +
           "main": {

     

       458
       458
       +
             "type": "query",

     

       459
       459
       +
             "output": {

     

       460
       460
       +
               "encoding": "application/json",

     

       461
       461
       +
               "schema": {

     

       462
       462
       +
                 "type": "object",

     

       463
       463
       +
                 "required": ["instances"],

     

       464
       464
       +
                 "properties": {

     

       465
       465
       +
                   "instances": {

     

       466
       466
       +
                     "type": "array",

     

       467
       467
       +
                     "items": { "$ref": "#instanceView" }

     

       468
       468
       +
                   }

     

       469
       469
       +
                 }

     

       470
       470
       +
               }

     

       471
       471
       +
             }

     

       472
       472
       +
           },

     

       473
       473
       +
           "instanceView": {

     

       474
       474
       +
             "type": "object",

     

       475
       475
       +
             "required": ["did", "domain", "trustLevel"],

     

       476
       476
       +
             "properties": {

     

       477
       477
       +
               "did": { "type": "string" },

     

       478
       478
       +
               "domain": { "type": "string" },

     

       479
       479
       +
               "trustLevel": { "type": "string" },

     

       480
       480
       +
               "allowedMethods": { "type": "array", "items": { "type": "string" } }

     

       481
       481
       +
             }

     

       482
       482
       +
           }

     

       483
       483
       +
         }

     

       484
       484
       +
       }

     

       485
       485
       +
       ```

     

       486
       486
       +
       

     

       487
       487
       +
       ### Modified Endpoint: `social.coves.community.post.create`

     

       488
       488
       +
       

     

       489
       489
       +
       **Changes:**

     

       490
       490
       +
       - No API contract changes

     

       491
       491
       +
       - Internal routing: local vs federated

     

       492
       492
       +
       - New error codes:

     

       493
       493
       +
         - `FederationFailed` - Remote instance unreachable

     

       494
       494
       +
         - `RemoteNotAuthorized` - Remote instance rejected auth

     

       495
       495
       +
         - `RemoteBanned` - User banned on remote community

     

       496
       496
       +
       

     

       497
       497
       +
       ---

     

       498
       498
       +
       

     

       499
       499
       +
       ## User Experience

     

       500
       500
       +
       

     

       501
       501
       +
       ### Happy Path: Cross-Instance Post

     

       502
       502
       +
       

     

       503
       503
       +
       1. User on coves.social navigates to !gaming@covesinstance.com

     

       504
       504
       +
       2. Clicks "Create Post"

     

       505
       505
       +
       3. Fills out post form (title, content, etc.)

     

       506
       506
       +
       4. Clicks "Submit"

     

       507
       507
       +
       5. **Behind the scenes:**

     

       508
       508
       +
          - coves.social requests service auth from covesinstance.com

     

       509
       509
       +
          - covesinstance.com validates and issues token

     

       510
       510
       +
          - coves.social writes post using token

     

       511
       511
       +
          - Post appears in feed within seconds (via firehose)

     

       512
       512
       +
       6. **User sees:** Post published successfully

     

       513
       513
       +
       7. Post appears in:

     

       514
       514
       +
          - covesinstance.com feeds (native community)

     

       515
       515
       +
          - coves.social discover/all feeds (indexed via firehose)

     

       516
       516
       +
          - User's profile on coves.social

     

       517
       517
       +
       

     

       518
       518
       +
       ### Error Cases

     

       519
       519
       +
       

     

       520
       520
       +
       **User Banned:**

     

       521
       521
       +
       - Error: "You are banned from !gaming@covesinstance.com"

     

       522
       522
       +
       - Suggestion: "Contact community moderators for more information"

     

       523
       523
       +
       

     

       524
       524
       +
       **Instance Blocked:**

     

       525
       525
       +
       - Error: "This community does not accept posts from your instance"

     

       526
       526
       +
       - Suggestion: "Contact community administrators or create a local account"

     

       527
       527
       +
       

     

       528
       528
       +
       **Federation Unavailable:**

     

       529
       529
       +
       - Error: "Unable to connect to covesinstance.com. Try again later."

     

       530
       530
       +
       - Fallback: Allow saving as draft (future feature)

     

       531
       531
       +
       

     

       532
       532
       +
       **Rate Limited:**

     

       533
       533
       +
       - Error: "You're posting too quickly. Please wait before posting again."

     

       534
       534
       +
       - Show: Countdown until next post allowed

     

       535
       535
       +
       

     

       536
       536
       +
       ---

     

       537
       537
       +
       

     

       538
       538
       +
       ## Testing Requirements

     

       539
       539
       +
       

     

       540
       540
       +
       ### Unit Tests

     

       541
       541
       +
       

     

       542
       542
       +
       1. **Service Detection:**

     

       543
       543
       +
          - `isLocalCommunity()` correctly identifies local vs remote

     

       544
       544
       +
          - Handles edge cases (different ports, subdomains)

     

       545
       545
       +
       

     

       546
       546
       +
       2. **Service Auth Client:**

     

       547
       547
       +
          - Correctly formats service auth requests

     

       548
       548
       +
          - Handles token expiration

     

       549
       549
       +
          - Retries on transient failures

     

       550
       550
       +
       

     

       551
       551
       +
       3. **Federated Post Creation:**

     

       552
       552
       +
          - Uses service auth token instead of community credentials

     

       553
       553
       +
          - Falls back gracefully on errors

     

       554
       554
       +
          - Logs federation events

     

       555
       555
       +
       

     

       556
       556
       +
       ### Integration Tests

     

       557
       557
       +
       

     

       558
       558
       +
       1. **Local Post (Regression):**

     

       559
       559
       +
          - Posting to local community still works

     

       560
       560
       +
          - No performance degradation

     

       561
       561
       +
       

     

       562
       562
       +
       2. **Federated Post:**

     

       563
       563
       +
          - User can post to remote community

     

       564
       564
       +
          - Service auth token requested correctly

     

       565
       565
       +
          - Post written to remote PDS

     

       566
       566
       +
          - Post indexed by both AppViews

     

       567
       567
       +
       

     

       568
       568
       +
       3. **Authorization Failures:**

     

       569
       569
       +
          - Banned users rejected at service auth stage

     

       570
       570
       +
          - Untrusted instances rejected

     

       571
       571
       +
          - Expired tokens rejected

     

       572
       572
       +
       

     

       573
       573
       +
       4. **Rate Limiting:**

     

       574
       574
       +
          - Per-user rate limits enforced

     

       575
       575
       +
          - Per-instance rate limits enforced

     

       576
       576
       +
          - Rate limit resets correctly

     

       577
       577
       +
       

     

       578
       578
       +
       ### End-to-End Tests

     

       579
       579
       +
       

     

       580
       580
       +
       1. **Cross-Instance User Journey:**

     

       581
       581
       +
          - Set up two instances (instance-a, instance-b)

     

       582
       582
       +
          - Create community on instance-b

     

       583
       583
       +
          - User on instance-a posts to instance-b community

     

       584
       584
       +
          - Verify post appears on both instances

     

       585
       585
       +
       

     

       586
       586
       +
       2. **Moderation Enforcement:**

     

       587
       587
       +
          - Ban user on remote instance

     

       588
       588
       +
          - Verify user can't post from any instance

     

       589
       589
       +
          - Unban user

     

       590
       590
       +
          - Verify user can post again

     

       591
       591
       +
       

     

       592
       592
       +
       3. **Instance Blocklist:**

     

       593
       593
       +
          - Block instance-a on instance-b

     

       594
       594
       +
          - Verify users from instance-a can't post to instance-b communities

     

       595
       595
       +
          - Unblock instance-a

     

       596
       596
       +
          - Verify posting works again

     

       597
       597
       +
       

     

       598
       598
       +
       ---

     

       599
       599
       +
       

     

       600
       600
       +
       ## Migration Path (Alpha → Beta)

     

       601
       601
       +
       

     

       602
       602
       +
       ### Phase 1: Backend Implementation (No User Impact)

     

       603
       603
       +
       1. Add service auth client

     

       604
       604
       +
       2. Add local vs remote detection

     

       605
       605
       +
       3. Deploy with feature flag `ENABLE_FEDERATION=false`

     

       606
       606
       +
       

     

       607
       607
       +
       ### Phase 2: Database Migration

     

       608
       608
       +
       1. Add federation tables

     

       609
       609
       +
       2. Seed with initial trusted instances (manual)

     

       610
       610
       +
       3. Add community federation flags (default: allow)

     

       611
       611
       +
       

     

       612
       612
       +
       ### Phase 3: Soft Launch

     

       613
       613
       +
       1. Enable federation for single test instance

     

       614
       614
       +
       2. Monitor service auth requests/errors

     

       615
       615
       +
       3. Validate rate limiting works

     

       616
       616
       +
       

     

       617
       617
       +
       ### Phase 4: Beta Rollout

     

       618
       618
       +
       1. Enable `ENABLE_FEDERATION=true` for all instances

     

       619
       619
       +
       2. Admin UI for managing trusted instances

     

       620
       620
       +
       3. Community settings for federation preferences

     

       621
       621
       +
       

     

       622
       622
       +
       ### Phase 5: Documentation & Onboarding

     

       623
       623
       +
       1. Instance operator guide: "How to federate with other instances"

     

       624
       624
       +
       2. Community moderator guide: "Federation settings"

     

       625
       625
       +
       3. User guide: "Posting across instances"

     

       626
       626
       +
       

     

       627
       627
       +
       ---

     

       628
       628
       +
       

     

       629
       629
       +
       ## Metrics & Success Criteria

     

       630
       630
       +
       

     

       631
       631
       +
       ### Performance Metrics

     

       632
       632
       +
       - Service auth request latency: p95 < 200ms

     

       633
       633
       +
       - Federated post creation time: p95 < 2 seconds (vs 500ms local)

     

       634
       634
       +
       - Service auth token cache hit rate: > 80%

     

       635
       635
       +
       

     

       636
       636
       +
       ### Adoption Metrics

     

       637
       637
       +
       - % of posts that are federated: Target 20% by end of Beta

     

       638
       638
       +
       - Number of federated instances: Target 5+ by end of Beta

     

       639
       639
       +
       - Cross-instance engagement (comments, votes): Monitor trend

     

       640
       640
       +
       

     

       641
       641
       +
       ### Reliability Metrics

     

       642
       642
       +
       - Service auth success rate: > 99%

     

       643
       643
       +
       - Federated post success rate: > 95%

     

       644
       644
       +
       - Service auth token validation errors: < 1%

     

       645
       645
       +
       

     

       646
       646
       +
       ### Security Metrics

     

       647
       647
       +
       - Unauthorized access attempts: Monitor & alert

     

       648
       648
       +
       - Rate limit triggers: Track per instance

     

       649
       649
       +
       - Ban evasion attempts: Zero tolerance

     

       650
       650
       +
       

     

       651
       651
       +
       ---

     

       652
       652
       +
       

     

       653
       653
       +
       ## Rollback Plan

     

       654
       654
       +
       

     

       655
       655
       +
       If federation causes critical issues:

     

       656
       656
       +
       

     

       657
       657
       +
       1. **Immediate:** Set `ENABLE_FEDERATION=false` via env var

     

       658
       658
       +
       2. **Fallback:** All posts route through local-only flow

     

       659
       659
       +
       3. **Investigation:** Review logs for service auth failures

     

       660
       660
       +
       4. **Fix Forward:** Deploy patch, re-enable gradually

     

       661
       661
       +
       

     

       662
       662
       +
       **No data loss:** Posts are written to PDS, indexed via firehose regardless of federation method.

     

       663
       663
       +
       

     

       664
       664
       +
       ---

     

       665
       665
       +
       

     

       666
       666
       +
       ## Open Questions

     

       667
       667
       +
       

     

       668
       668
       +
       1. **Instance Discovery:** How do users find communities on other instances?

     

       669
       669
       +
          - Beta: Manual (users share links)

     

       670
       670
       +
          - Future: Instance directory, community search across instances

     

       671
       671
       +
       

     

       672
       672
       +
       2. **Service Auth Token Caching:** Should AppViews cache service auth tokens?

     

       673
       673
       +
          - Pros: Reduce latency, fewer PDS requests

     

       674
       674
       +
          - Cons: Stale permissions, ban enforcement delay

     

       675
       675
       +
          - **Decision needed:** Cache with short TTL (5 minutes)?

     

       676
       676
       +
       

     

       677
       677
       +
       3. **PDS Implementation:** Who implements service auth validation?

     

       678
       678
       +
          - Option A: Contribute to official PDS (long timeline)

     

       679
       679
       +
          - Option B: Run forked PDS (maintenance burden)

     

       680
       680
       +
          - Option C: Proxy/middleware (added complexity)

     

       681
       681
       +
          - **Decision needed:** Start with Option B, migrate to Option A?

     

       682
       682
       +
       

     

       683
       683
       +
       4. **Federation Symmetry:** If instance-a trusts instance-b, does instance-b auto-trust instance-a?

     

       684
       684
       +
          - Beta: No (asymmetric trust)

     

       685
       685
       +
          - Future: Mutual federation agreements?

     

       686
       686
       +
       

     

       687
       687
       +
       5. **Cross-Instance Moderation:** Should bans propagate across instances?

     

       688
       688
       +
          - Beta: No (each instance decides)

     

       689
       689
       +
          - Future: Shared moderation lists?

     

       690
       690
       +
       

     

       691
       691
       +
       ---

     

       692
       692
       +
       

     

       693
       693
       +
       ## Future Enhancements (Post-Beta)

     

       694
       694
       +
       

     

       695
       695
       +
       1. **Service Auth Token Caching:** Reduce latency for frequent posters

     

       696
       696
       +
       2. **Batch Service Auth:** Request tokens for multiple communities at once

     

       697
       697
       +
       3. **Instance Discovery API:** Automatic instance detection/registration

     

       698
       698
       +
       4. **Federation Analytics:** Dashboard showing cross-instance activity

     

       699
       699
       +
       5. **Moderation Sync:** Optional shared ban lists across trusted instances

     

       700
       700
       +
       6. **Content Mirroring:** Cache federated posts locally for performance

     

       701
       701
       +
       7. **User Migration:** Transfer account between instances

     

       702
       702
       +
       

     

       703
       703
       +
       ---

     

       704
       704
       +
       

     

       705
       705
       +
       ## Resources

     

       706
       706
       +
       

     

       707
       707
       +
       ### Documentation

     

       708
       708
       +
       - [atProto Service Auth Spec](https://atproto.com/specs/service-auth) (hypothetical - check actual docs)

     

       709
       709
       +
       - Lemmy Federation Architecture

     

       710
       710
       +
       - Mastodon Federation Implementation

     

       711
       711
       +
       

     

       712
       712
       +
       ### Code References

     

       713
       713
       +
       - `internal/core/posts/service.go` - Post creation service

     

       714
       714
       +
       - `internal/api/handlers/post/create.go` - Post creation handler

     

       715
       715
       +
       - `internal/atproto/jetstream/` - Firehose consumers

     

       716
       716
       +
       

     

       717
       717
       +
       ### Dependencies

     

       718
       718
       +
       - atproto SDK (for service auth)

     

       719
       719
       +
       - PDS v0.4+ (service auth support)

     

       720
       720
       +
       - PostgreSQL 14+ (for federation tables)

     

       721
       721
       +
       

     

       722
       722
       +
       ---

     

       723
       723
       +
       

     

       724
       724
       +
       ## Appendix A: Service Auth Request Example

     

       725
       725
       +
       

     

       726
       726
       +
       **Request to Remote PDS:**

     

       727
       727
       +
       ```http

     

       728
       728
       +
       POST https://covesinstance.com/xrpc/com.atproto.server.getServiceAuth

     

       729
       729
       +
       Authorization: Bearer {coves-social-instance-jwt}

     

       730
       730
       +
       Content-Type: application/json

     

       731
       731
       +
       

     

       732
       732
       +
       {

     

       733
       733
       +
         "aud": "did:plc:community123",

     

       734
       734
       +
         "exp": 1700000000,

     

       735
       735
       +
         "lxm": "social.coves.community.post.create"

     

       736
       736
       +
       }

     

       737
       737
       +
       ```

     

       738
       738
       +
       

     

       739
       739
       +
       **Response:**

     

       740
       740
       +
       ```http

     

       741
       741
       +
       HTTP/1.1 200 OK

     

       742
       742
       +
       Content-Type: application/json

     

       743
       743
       +
       

     

       744
       744
       +
       {

     

       745
       745
       +
         "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."

     

       746
       746
       +
       }

     

       747
       747
       +
       ```

     

       748
       748
       +
       

     

       749
       749
       +
       **Using Token to Create Post:**

     

       750
       750
       +
       ```http

     

       751
       751
       +
       POST https://covesinstance.com/xrpc/com.atproto.repo.createRecord

     

       752
       752
       +
       Authorization: Bearer {service-auth-token}

     

       753
       753
       +
       Content-Type: application/json

     

       754
       754
       +
       

     

       755
       755
       +
       {

     

       756
       756
       +
         "repo": "did:plc:community123",

     

       757
       757
       +
         "collection": "social.coves.community.post",

     

       758
       758
       +
         "record": {

     

       759
       759
       +
           "$type": "social.coves.community.post",

     

       760
       760
       +
           "community": "did:plc:community123",

     

       761
       761
       +
           "author": "did:plc:user456",

     

       762
       762
       +
           "title": "Hello from coves.social!",

     

       763
       763
       +
           "content": "This is a federated post",

     

       764
       764
       +
           "createdAt": "2024-11-16T12:00:00Z"

     

       765
       765
       +
         }

     

       766
       766
       +
       }

     

       767
       767
       +
       ```

     

       768
       768
       +
       

     

       769
       769
       +
       ---

     

       770
       770
       +
       

     

       771
       771
       +
       ## Appendix B: Error Handling Matrix

     

       772
       772
       +
       

     

       773
       773
       +
       | Error Condition | HTTP Status | Error Code | User Message | Retry Strategy |

     

       774
       774
       +
       |----------------|-------------|------------|--------------|----------------|

     

       775
       775
       +
       | Instance not trusted | 403 | `UntrustedInstance` | "This community doesn't accept posts from your instance" | No retry |

     

       776
       776
       +
       | User banned | 403 | `Banned` | "You are banned from this community" | No retry |

     

       777
       777
       +
       | Rate limit exceeded | 429 | `RateLimited` | "Too many posts. Try again in X minutes" | Exponential backoff |

     

       778
       778
       +
       | PDS unreachable | 503 | `ServiceUnavailable` | "Community temporarily unavailable" | Retry 3x with backoff |

     

       779
       779
       +
       | Invalid token | 401 | `InvalidToken` | "Session expired. Please try again" | Refresh token & retry |

     

       780
       780
       +
       | Community not found | 404 | `CommunityNotFound` | "Community not found" | No retry |

     

       781
       781
       +
       | Service auth failed | 500 | `FederationFailed` | "Unable to connect. Try again later" | Retry 2x |

     

       782
       782
       +
       

     

       783
       783
       +
       ---

     

       784
       784
       +
       

     

       785
       785
       +
       **End of PRD**

+130 -28

docs/PRD_ALPHA_GO_LIVE.md

···

       7
       7
        
       ## 🎯 Major Progress Update

     

       8
       8
        
       

     

       9
       9
        
       **✅ ALL E2E TESTS COMPLETE!** (Completed 2025-11-16)

     

       10
       10
       +
       **✅ BIDIRECTIONAL DID VERIFICATION COMPLETE!** (Completed 2025-11-16)

     

       10
       11
        
       

     

       11
       12
        
       All 6 critical E2E test suites have been implemented and are passing:

     

       12
       13
        
       - ✅ Full User Journey (signup → community → post → comment → vote)

     
···

       19
       20
        
       **Time Saved**: ~7-12 hours through parallel agent implementation

     

       20
       21
        
       **Test Quality**: Enhanced with comprehensive database record verification to catch race conditions

     

       21
       22
        
       

     

       23
       23
       +
       ### Production Deployment Requirements

     

       24
       24
       +
       

     

       25
       25
       +
       **Architecture**:

     

       26
       26
       +
       - **AppView Domain**: coves.social (instance identity, API, frontend)

     

       27
       27
       +
       - **PDS Domain**: coves.me (separate domain required - cannot be same as AppView)

     

       28
       28
       +
       - **Community Handles**: Use @coves.social (AppView domain)

     

       29
       29
       +
       - **Jetstream**: Connects to Bluesky's production firehose (wss://jetstream2.us-east.bsky.network)

     

       30
       30
       +
       

     

       31
       31
       +
       **Required: .well-known/did.json at coves.social**:

     

       32
       32
       +
       ```json

     

       33
       33
       +
       {

     

       34
       34
       +
         "id": "did:web:coves.social",

     

       35
       35
       +
         "alsoKnownAs": ["at://coves.social"],

     

       36
       36
       +
         "verificationMethod": [

     

       37
       37
       +
           {

     

       38
       38
       +
             "id": "did:web:coves.social#atproto",

     

       39
       39
       +
             "type": "Multikey",

     

       40
       40
       +
             "controller": "did:web:coves.social",

     

       41
       41
       +
             "publicKeyMultibase": "z..."

     

       42
       42
       +
           }

     

       43
       43
       +
         ],

     

       44
       44
       +
         "service": [

     

       45
       45
       +
           {

     

       46
       46
       +
             "id": "#atproto_pds",

     

       47
       47
       +
             "type": "AtprotoPersonalDataServer",

     

       48
       48
       +
             "serviceEndpoint": "https://coves.me"

     

       49
       49
       +
           }

     

       50
       50
       +
         ]

     

       51
       51
       +
       }

     

       52
       52
       +
       ```

     

       53
       53
       +
       

     

       54
       54
       +
       **Environment Variables**:

     

       55
       55
       +
       - AppView:

     

       56
       56
       +
         - `INSTANCE_DID=did:web:coves.social`

     

       57
       57
       +
         - `INSTANCE_DOMAIN=coves.social`

     

       58
       58
       +
         - `PDS_URL=https://coves.me` (separate domain)

     

       59
       59
       +
         - `SKIP_DID_WEB_VERIFICATION=false` (production)

     

       60
       60
       +
         - `JETSTREAM_URL=wss://jetstream2.us-east.bsky.network/subscribe`

     

       61
       61
       +
       

     

       62
       62
       +
       **Verification**:

     

       63
       63
       +
       - `curl https://coves.social/.well-known/did.json` (should return DID document)

     

       64
       64
       +
       - `curl https://coves.me/xrpc/_health` (PDS health check)

     

       65
       65
       +
       

     

       22
       66
        
       ## Overview

     

       23
       67
        
       

     

       24
       68
        
       This document tracks the remaining work required to launch Coves alpha with real users. Focus is on critical functionality, security, and operational readiness.

     
···

       29
       73
        
       

     

       30
       74
        
       ### 1. Authentication & Security

     

       31
       75
        
       

     

       76
       76
       +
       #### Production PDS Deployment

     

       77
       77
       +
       **CRITICAL**: PDS must be on separate domain from AppView (coves.me, not coves.social)

     

       78
       78
       +
       

     

       79
       79
       +
       - [ ] Deploy PDS to coves.me domain

     

       80
       80
       +
         - [ ] Set up DNS: A record for coves.me → server IP

     

       81
       81
       +
         - [ ] Configure SSL certificate for coves.me

     

       82
       82
       +
         - [ ] Deploy PDS container/service on port 2583

     

       83
       83
       +
         - [ ] Configure nginx/Caddy reverse proxy for coves.me → localhost:2583

     

       84
       84
       +
         - [ ] Set PDS_HOSTNAME=coves.me in PDS environment

     

       85
       85
       +
         - [ ] Mount persistent volume for PDS data (/pds/data)

     

       86
       86
       +
       - [ ] Verify PDS connectivity

     

       87
       87
       +
         - [ ] Test: `curl https://coves.me/xrpc/_health`

     

       88
       88
       +
         - [ ] Create test community account on PDS

     

       89
       89
       +
         - [ ] Verify JWKS endpoint: `curl https://coves.me/.well-known/jwks.json`

     

       90
       90
       +
         - [ ] Test community account token provisioning

     

       91
       91
       +
       - [ ] Configure AppView to use production PDS

     

       92
       92
       +
         - [ ] Set `PDS_URL=https://coves.me` in AppView .env

     

       93
       93
       +
         - [ ] Test community creation flow (provisions account on coves.me)

     

       94
       94
       +
         - [ ] Verify account provisioning works end-to-end

     

       95
       95
       +
       

     

       96
       96
       +
       **Important**: Jetstream connects to Bluesky's production firehose, which automatically includes events from all production PDS instances (including coves.me once it's live)

     

       97
       97
       +
       

     

       98
       98
       +
       **Estimated Effort**: 4-6 hours

     

       99
       99
       +
       **Risk**: Medium (infrastructure setup, DNS propagation)

     

       100
       100
       +
       

     

       32
       101
        
       #### JWT Signature Verification (Production Mode)

     

       33
       33
       -
       - [ ] Test with production PDS at `pds.bretton.dev`

     

       34
       34
       -
         - [ ] Create test account on production PDS

     

       35
       35
       -
         - [ ] Verify JWKS endpoint is accessible

     

       102
       102
       +
       - [ ] Test with production PDS at coves.me

     

       103
       103
       +
         - [ ] Verify JWKS endpoint is accessible: `https://coves.me/.well-known/jwks.json`

     

       36
       104
        
         - [ ] Run `TestJWTSignatureVerification` against production PDS

     

       37
       105
        
         - [ ] Confirm signature verification succeeds

     

       38
       38
       -
         - [ ] Test token refresh flow

     

       106
       106
       +
         - [ ] Test token refresh flow for community accounts

     

       39
       107
        
       - [ ] Set `AUTH_SKIP_VERIFY=false` in production environment

     

       40
       108
        
       - [ ] Verify all auth middleware tests pass with verification enabled

     

       41
       41
       -
       - [ ] Document production PDS requirements for communities

     

       42
       42
       -
       

     

       43
       43
       -
       **Estimated Effort**: 2-3 hours

     

       44
       44
       -
       **Risk**: Medium (code implemented, needs validation)

     

       45
       45
       -
       

     

       46
       46
       -
       #### did:web Verification

     

       47
       47
       -
       - [ ] Complete did:web domain verification implementation

     

       48
       48
       -
       - [ ] Test with real did:web identities

     

       49
       49
       -
       - [ ] Add security logging for verification failures

     

       50
       50
       -
       - [ ] Set `SKIP_DID_WEB_VERIFICATION=false` for production

     

       51
       109
        
       

     

       52
       110
        
       **Estimated Effort**: 2-3 hours

     

       53
       53
       -
       **Risk**: Medium

     

       111
       111
       +
       **Risk**: Low (depends on PDS deployment)

     

       112
       112
       +
       

     

       113
       113
       +
       #### did:web Verification ✅ COMPLETE

     

       114
       114
       +
       - [x] Complete did:web domain verification implementation (2025-11-16)

     

       115
       115
       +
       - [x] Implement Bluesky-compatible bidirectional verification

     

       116
       116
       +
       - [x] Add alsoKnownAs field verification in DID documents

     

       117
       117
       +
       - [x] Add security logging for verification failures

     

       118
       118
       +
       - [x] Update cache TTL to 24h (matches Bluesky recommendations)

     

       119
       119
       +
       - [x] Comprehensive test coverage with mock HTTP servers

     

       120
       120
       +
       - [ ] Set `SKIP_DID_WEB_VERIFICATION=false` for production (dev default: true)

     

       121
       121
       +
       - [ ] Deploy `.well-known/did.json` to production domain

     

       122
       122
       +
       

     

       123
       123
       +
       **Implementation Details**:

     

       124
       124
       +
       - **Location**: [internal/atproto/jetstream/community_consumer.go](../internal/atproto/jetstream/community_consumer.go)

     

       125
       125
       +
       - **Verification Flow**: Domain matching + DID document fetch + alsoKnownAs validation

     

       126
       126
       +
       - **Security Model**: Matches Bluesky (DNS/HTTPS authority + bidirectional binding)

     

       127
       127
       +
       - **Performance**: Bounded LRU cache (1000 entries), rate limiting (10 req/s), 24h TTL

     

       128
       128
       +
       - **Impact**: AppView indexing and federation trust (not community creation API)

     

       129
       129
       +
       - **Tests**: `tests/integration/community_hostedby_security_test.go`

     

       130
       130
       +
       

     

       131
       131
       +
       **Actual Effort**: 3 hours (implementation + testing)

     

       132
       132
       +
       **Risk**: ✅ Low (complete and tested)

     

       54
       133
        
       

     

       55
       134
        
       ### 2. DPoP Token Architecture Fix

     

       56
       135
        
       

     
···

       172
       251
        
         - [ ] Common issues and fixes

     

       173
       252
        
         - [ ] Emergency procedures (PDS down, database down, etc.)

     

       174
       253
        
       - [ ] Create production environment checklist

     

       175
       175
       -
         - [ ] All environment variables set

     

       176
       176
       -
         - [ ] `AUTH_SKIP_VERIFY=false`

     

       177
       177
       -
         - [ ] `SKIP_DID_WEB_VERIFICATION=false`

     

       178
       178
       -
         - [ ] Database migrations applied

     

       179
       179
       -
         - [ ] PDS connectivity verified

     

       180
       180
       -
         - [ ] JWKS caching working

     

       181
       181
       -
         - [ ] Jetstream consumers running

     

       254
       254
       +
         - [ ] **Domain Setup**

     

       255
       255
       +
           - [ ] AppView domain (coves.social) DNS configured

     

       256
       256
       +
           - [ ] PDS domain (coves.me) DNS configured - MUST be separate domain

     

       257
       257
       +
           - [ ] SSL certificates for both domains

     

       258
       258
       +
           - [ ] Nginx/Caddy reverse proxy configured for both domains

     

       259
       259
       +
         - [ ] **AppView Environment Variables**

     

       260
       260
       +
           - [ ] `INSTANCE_DID=did:web:coves.social`

     

       261
       261
       +
           - [ ] `INSTANCE_DOMAIN=coves.social`

     

       262
       262
       +
           - [ ] `PDS_URL=https://coves.me` (separate domain)

     

       263
       263
       +
           - [ ] `AUTH_SKIP_VERIFY=false`

     

       264
       264
       +
           - [ ] `SKIP_DID_WEB_VERIFICATION=false`

     

       265
       265
       +
           - [ ] `JETSTREAM_URL=wss://jetstream2.us-east.bsky.network/subscribe`

     

       266
       266
       +
         - [ ] **PDS Environment Variables**

     

       267
       267
       +
           - [ ] `PDS_HOSTNAME=coves.me`

     

       268
       268
       +
           - [ ] `PDS_PORT=2583`

     

       269
       269
       +
           - [ ] Persistent storage mounted

     

       270
       270
       +
         - [ ] **Deployment Verification**

     

       271
       271
       +
           - [ ] Deploy `.well-known/did.json` to coves.social with `serviceEndpoint: https://coves.me`

     

       272
       272
       +
           - [ ] Verify: `curl https://coves.social/.well-known/did.json`

     

       273
       273
       +
           - [ ] Verify: `curl https://coves.me/xrpc/_health`

     

       274
       274
       +
           - [ ] Database migrations applied

     

       275
       275
       +
           - [ ] PDS connectivity verified from AppView

     

       276
       276
       +
           - [ ] JWKS caching working

     

       277
       277
       +
           - [ ] Jetstream consumer connected to Bluesky production firehose

     

       278
       278
       +
           - [ ] Test community creation end-to-end

     

       182
       279
        
         - [ ] Monitoring and alerting active

     

       183
       280
        
       

     

       184
       281
        
       **Estimated Effort**: 6-8 hours

     
···

       342
       439
        
       ## Timeline Estimate

     

       343
       440
        
       

     

       344
       441
        
       ### Week 1: Critical Blockers (P0)

     

       345
       345
       -
       - **Days 1-2**: Authentication (JWT + did:web verification)

     

       442
       442
       +
       - ~~**Days 1-2**: Authentication (JWT + did:web verification)~~ ✅ **did:web COMPLETED**

     

       443
       443
       +
       - **Day 1**: Production PDS deployment (coves.me domain setup)

     

       444
       444
       +
       - **Day 2**: JWT signature verification with production PDS

     

       346
       445
        
       - **Day 3**: DPoP token architecture fix

     

       347
       446
        
       - ~~**Day 4**: Handle resolution + comment count reconciliation~~ ✅ **COMPLETED**

     

       348
       447
        
       - **Day 4-5**: Testing and bug fixes

     

       349
       448
        
       

     

       350
       350
       -
       **Total**: 15-20 hours (reduced from 20-25 due to completed items)

     

       449
       449
       +
       **Total**: 16-23 hours (added 4-6 hours for PDS deployment, reduced from original due to did:web completion)

     

       351
       450
        
       

     

       352
       451
        
       ### Week 2: Production Infrastructure (P1)

     

       353
       452
        
       - **Days 6-7**: Monitoring + structured logging

     
···

       363
       462
        
       

     

       364
       463
        
       **Total**: ~~20-25 hours~~ → **13 hours actual** (E2E tests) + 7-12 hours remaining (load testing, polish)

     

       365
       464
        
       

     

       366
       366
       -
       **Grand Total: ~~65-80 hours~~ → 50-65 hours remaining (approximately 1.5-2 weeks full-time)**

     

       367
       367
       -
       *(Originally 70-85 hours. Reduced by completed items: handle resolution, comment count reconciliation, and ALL E2E tests)*

     

       465
       465
       +
       **Grand Total: ~~65-80 hours~~ → 51-68 hours remaining (approximately 1.5-2 weeks full-time)**

     

       466
       466
       +
       *(Originally 70-85 hours. Adjusted for: +4-6 hours PDS deployment, -3 hours did:web completion, -13 hours E2E tests completion, -4 hours handle resolution and comment reconciliation)*

     

       368
       467
        
       

     

       369
       468
        
       **✅ Progress Update**: E2E testing section COMPLETE ahead of schedule - saved ~7-12 hours through parallel agent implementation

     

       370
       469
        
       

     
···

       377
       476
        
       - [ ] All P0 blockers resolved

     

       378
       477
        
         - ✅ Handle resolution (COMPLETE)

     

       379
       478
        
         - ✅ Comment count reconciliation (COMPLETE)

     

       479
       479
       +
         - ✅ did:web verification (COMPLETE - needs production deployment)

     

       480
       480
       +
         - [ ] Production PDS deployed to coves.me (separate domain)

     

       380
       481
        
         - [ ] JWT signature verification working with production PDS

     

       381
       482
        
         - [ ] DPoP architecture fix implemented

     

       382
       382
       -
         - [ ] did:web verification complete

     

       383
       483
        
       - [ ] Subscriptions/blocking work via client-write pattern

     

       384
       484
        
       - [x] **All integration tests passing** ✅

     

       385
       485
        
       - [x] **E2E user journey test passing** ✅

     
···

       461
       561
        
       11. [ ] Go/no-go decision

     

       462
       562
        
       12. [ ] Launch! 🚀

     

       463
       563
        
       

     

       464
       464
       -
       **🎉 Major Milestone**: All E2E tests complete! Test coverage now includes full user journey, blob uploads, concurrent operations, rate limiting, and error recovery.

     

       564
       564
       +
       **🎉 Major Milestones**:

     

       565
       565
       +
       - All E2E tests complete! Test coverage now includes full user journey, blob uploads, concurrent operations, rate limiting, and error recovery.

     

       566
       566
       +
       - Bidirectional DID verification complete! Bluesky-compatible security model with alsoKnownAs validation, 24h cache TTL, and comprehensive test coverage.

+18

internal/api/routes/aggregator.go

···

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
        
       	"Coves/internal/api/handlers/aggregator"

     

       5
       5
       +
       	"Coves/internal/api/middleware"

     

       6
       6
       +
       	"Coves/internal/atproto/identity"

     

       5
       7
        
       	"Coves/internal/core/aggregators"

     

       8
       8
       +
       	"Coves/internal/core/users"

     

       9
       9
       +
       	"net/http"

     

       10
       10
       +
       	"time"

     

       6
       11
        
       

     

       7
       12
        
       	"github.com/go-chi/chi/v5"

     

       8
       13
        
       )

     
···

       12
       17
        
       func RegisterAggregatorRoutes(

     

       13
       18
        
       	r chi.Router,

     

       14
       19
        
       	aggregatorService aggregators.Service,

     

       20
       20
       +
       	userService users.UserService,

     

       21
       21
       +
       	identityResolver identity.Resolver,

     

       15
       22
        
       ) {

     

       16
       23
        
       	// Create query handlers

     

       17
       24
        
       	getServicesHandler := aggregator.NewGetServicesHandler(aggregatorService)

     

       18
       25
        
       	getAuthorizationsHandler := aggregator.NewGetAuthorizationsHandler(aggregatorService)

     

       19
       26
        
       	listForCommunityHandler := aggregator.NewListForCommunityHandler(aggregatorService)

     

       20
       27
        
       

     

       28
       28
       +
       	// Create registration handler

     

       29
       29
       +
       	registerHandler := aggregator.NewRegisterHandler(userService, identityResolver)

     

       30
       30
       +
       

     

       21
       31
        
       	// Query endpoints (public - no auth required)

     

       22
       32
        
       	// GET /xrpc/social.coves.aggregator.getServices?dids=did:plc:abc,did:plc:def

     

       23
       33
        
       	// Following app.bsky.feed.getFeedGenerators pattern

     
···

       31
       41
        
       	// Lists aggregators authorized by a community

     

       32
       42
        
       	r.Get("/xrpc/social.coves.aggregator.listForCommunity", listForCommunityHandler.HandleListForCommunity)

     

       33
       43
        
       

     

       44
       44
       +
       	// Registration endpoint (public - no auth required)

     

       45
       45
       +
       	// Aggregators register themselves after creating their own PDS accounts

     

       46
       46
       +
       	// POST /xrpc/social.coves.aggregator.register

     

       47
       47
       +
       	// Rate limited to 10 requests per 10 minutes per IP to prevent abuse

     

       48
       48
       +
       	registrationRateLimiter := middleware.NewRateLimiter(10, 10*time.Minute)

     

       49
       49
       +
       	r.Post("/xrpc/social.coves.aggregator.register",

     

       50
       50
       +
       		registrationRateLimiter.Middleware(http.HandlerFunc(registerHandler.HandleRegister)).ServeHTTP)

     

       51
       51
       +
       

     

       34
       52
        
       	// Write endpoints (Phase 2 - require authentication and moderator permissions)

     

       35
       53
        
       	// TODO: Implement after Jetstream consumer is ready

     

       36
       54
        
       	// POST /xrpc/social.coves.aggregator.enable (requires auth + moderator)

+591

docs/aggregators/SETUP_GUIDE.md

···

       1
       1
       +
       # Aggregator Setup Guide

     

       2
       2
       +
       

     

       3
       3
       +
       This guide explains how to set up and register an aggregator with Coves instances.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Table of Contents

     

       6
       6
       +
       

     

       7
       7
       +
       - [Overview](#overview)

     

       8
       8
       +
       - [Architecture](#architecture)

     

       9
       9
       +
       - [Prerequisites](#prerequisites)

     

       10
       10
       +
       - [Quick Start](#quick-start)

     

       11
       11
       +
       - [Detailed Setup Steps](#detailed-setup-steps)

     

       12
       12
       +
       - [Authorization Process](#authorization-process)

     

       13
       13
       +
       - [Posting to Communities](#posting-to-communities)

     

       14
       14
       +
       - [Rate Limits](#rate-limits)

     

       15
       15
       +
       - [Security Best Practices](#security-best-practices)

     

       16
       16
       +
       - [Troubleshooting](#troubleshooting)

     

       17
       17
       +
       - [API Reference](#api-reference)

     

       18
       18
       +
       

     

       19
       19
       +
       ## Overview

     

       20
       20
       +
       

     

       21
       21
       +
       **Aggregators** are automated services that post content to Coves communities. They are similar to Bluesky's feed generators and labelers - self-managed external services that integrate with the platform.

     

       22
       22
       +
       

     

       23
       23
       +
       **Key characteristics**:

     

       24
       24
       +
       - Self-owned: You create and manage your own PDS account

     

       25
       25
       +
       - Domain-verified: Prove ownership via `.well-known/atproto-did`

     

       26
       26
       +
       - Community-authorized: Moderators grant posting permission per-community

     

       27
       27
       +
       - Rate-limited: 10 posts per hour per community

     

       28
       28
       +
       

     

       29
       29
       +
       **Example use cases**:

     

       30
       30
       +
       - RSS feed aggregators (tech news, blog posts)

     

       31
       31
       +
       - Social media cross-posters (Twitter → Coves)

     

       32
       32
       +
       - Event notifications (GitHub releases, weather alerts)

     

       33
       33
       +
       - Content curation bots (daily links, summaries)

     

       34
       34
       +
       

     

       35
       35
       +
       ## Architecture

     

       36
       36
       +
       

     

       37
       37
       +
       ### Data Flow

     

       38
       38
       +
       

     

       39
       39
       +
       ```

     

       40
       40
       +
       ┌──────────────────────────────────────────────────────────┐

     

       41
       41
       +
       │ 1. One-Time Setup                                        │

     

       42
       42
       +
       ├──────────────────────────────────────────────────────────┤

     

       43
       43
       +
       │ Aggregator creates PDS account                           │

     

       44
       44
       +
       │   ↓                                                       │

     

       45
       45
       +
       │ Proves domain ownership (.well-known)                    │

     

       46
       46
       +
       │   ↓                                                       │

     

       47
       47
       +
       │ Registers with Coves (enters users table)                │

     

       48
       48
       +
       │   ↓                                                       │

     

       49
       49
       +
       │ Writes service declaration                               │

     

       50
       50
       +
       │   ↓                                                       │

     

       51
       51
       +
       │ Jetstream indexes into aggregators table                 │

     

       52
       52
       +
       └──────────────────────────────────────────────────────────┘

     

       53
       53
       +
       

     

       54
       54
       +
       ┌──────────────────────────────────────────────────────────┐

     

       55
       55
       +
       │ 2. Per-Community Authorization                           │

     

       56
       56
       +
       ├──────────────────────────────────────────────────────────┤

     

       57
       57
       +
       │ Moderator writes authorization record                    │

     

       58
       58
       +
       │   ↓                                                       │

     

       59
       59
       +
       │ Jetstream indexes into aggregator_authorizations         │

     

       60
       60
       +
       └──────────────────────────────────────────────────────────┘

     

       61
       61
       +
       

     

       62
       62
       +
       ┌──────────────────────────────────────────────────────────┐

     

       63
       63
       +
       │ 3. Posting (Ongoing)                                     │

     

       64
       64
       +
       ├──────────────────────────────────────────────────────────┤

     

       65
       65
       +
       │ Aggregator calls post creation endpoint                  │

     

       66
       66
       +
       │   ↓                                                       │

     

       67
       67
       +
       │ Handler validates:                                        │

     

       68
       68
       +
       │   - Author in users table ✓                              │

     

       69
       69
       +
       │   - Author in aggregators table ✓                        │

     

       70
       70
       +
       │   - Authorization exists ✓                               │

     

       71
       71
       +
       │   - Rate limit not exceeded ✓                            │

     

       72
       72
       +
       │   ↓                                                       │

     

       73
       73
       +
       │ Post written to community's PDS                          │

     

       74
       74
       +
       │   ↓                                                       │

     

       75
       75
       +
       │ Jetstream indexes post                                   │

     

       76
       76
       +
       └──────────────────────────────────────────────────────────┘

     

       77
       77
       +
       ```

     

       78
       78
       +
       

     

       79
       79
       +
       ### Database Tables

     

       80
       80
       +
       

     

       81
       81
       +
       **users** - All actors (users, communities, aggregators)

     

       82
       82
       +
       ```sql

     

       83
       83
       +
       CREATE TABLE users (

     

       84
       84
       +
           did TEXT PRIMARY KEY,

     

       85
       85
       +
           handle TEXT NOT NULL,

     

       86
       86
       +
           pds_url TEXT,

     

       87
       87
       +
           indexed_at TIMESTAMPTZ

     

       88
       88
       +
       );

     

       89
       89
       +
       ```

     

       90
       90
       +
       

     

       91
       91
       +
       **aggregators** - Aggregator-specific metadata

     

       92
       92
       +
       ```sql

     

       93
       93
       +
       CREATE TABLE aggregators (

     

       94
       94
       +
           did TEXT PRIMARY KEY,

     

       95
       95
       +
           display_name TEXT NOT NULL,

     

       96
       96
       +
           description TEXT,

     

       97
       97
       +
           avatar_url TEXT,

     

       98
       98
       +
           config_schema JSONB,

     

       99
       99
       +
           source_url TEXT,

     

       100
       100
       +
           maintainer_did TEXT,

     

       101
       101
       +
           record_uri TEXT NOT NULL UNIQUE,

     

       102
       102
       +
           record_cid TEXT NOT NULL,

     

       103
       103
       +
           created_at TIMESTAMPTZ,

     

       104
       104
       +
           indexed_at TIMESTAMPTZ

     

       105
       105
       +
       );

     

       106
       106
       +
       ```

     

       107
       107
       +
       

     

       108
       108
       +
       **aggregator_authorizations** - Community authorizations

     

       109
       109
       +
       ```sql

     

       110
       110
       +
       CREATE TABLE aggregator_authorizations (

     

       111
       111
       +
           id BIGSERIAL PRIMARY KEY,

     

       112
       112
       +
           aggregator_did TEXT NOT NULL,

     

       113
       113
       +
           community_did TEXT NOT NULL,

     

       114
       114
       +
           enabled BOOLEAN NOT NULL DEFAULT true,

     

       115
       115
       +
           config JSONB,

     

       116
       116
       +
           created_by TEXT,

     

       117
       117
       +
           record_uri TEXT NOT NULL UNIQUE,

     

       118
       118
       +
           record_cid TEXT NOT NULL,

     

       119
       119
       +
           UNIQUE(aggregator_did, community_did)

     

       120
       120
       +
       );

     

       121
       121
       +
       ```

     

       122
       122
       +
       

     

       123
       123
       +
       ## Prerequisites

     

       124
       124
       +
       

     

       125
       125
       +
       1. **Domain ownership**: You must own a domain where you can host static files over HTTPS

     

       126
       126
       +
       2. **Web server**: Ability to serve the `.well-known/atproto-did` file

     

       127
       127
       +
       3. **Development tools**: `curl`, `jq`, basic shell scripting knowledge

     

       128
       128
       +
       4. **Email address**: For creating the PDS account

     

       129
       129
       +
       

     

       130
       130
       +
       **Optional**:

     

       131
       131
       +
       - Custom avatar image (PNG/JPEG/WebP, max 1MB)

     

       132
       132
       +
       - GitHub repository for source code transparency

     

       133
       133
       +
       

     

       134
       134
       +
       ## Quick Start

     

       135
       135
       +
       

     

       136
       136
       +
       We provide automated setup scripts:

     

       137
       137
       +
       

     

       138
       138
       +
       ```bash

     

       139
       139
       +
       cd scripts/aggregator-setup

     

       140
       140
       +
       

     

       141
       141
       +
       # Make scripts executable

     

       142
       142
       +
       chmod +x *.sh

     

       143
       143
       +
       

     

       144
       144
       +
       # Run setup scripts in order

     

       145
       145
       +
       ./1-create-pds-account.sh

     

       146
       146
       +
       ./2-setup-wellknown.sh

     

       147
       147
       +
       # (Upload .well-known to your web server)

     

       148
       148
       +
       ./3-register-with-coves.sh

     

       149
       149
       +
       ./4-create-service-declaration.sh

     

       150
       150
       +
       ```

     

       151
       151
       +
       

     

       152
       152
       +
       See [scripts/aggregator-setup/README.md](../../scripts/aggregator-setup/README.md) for detailed script documentation.

     

       153
       153
       +
       

     

       154
       154
       +
       ## Detailed Setup Steps

     

       155
       155
       +
       

     

       156
       156
       +
       ### Step 1: Create PDS Account

     

       157
       157
       +
       

     

       158
       158
       +
       Your aggregator needs its own atProto identity (DID). The easiest way is to create an account on an existing PDS.

     

       159
       159
       +
       

     

       160
       160
       +
       **Using an existing PDS (recommended)**:

     

       161
       161
       +
       

     

       162
       162
       +
       ```bash

     

       163
       163
       +
       curl -X POST https://bsky.social/xrpc/com.atproto.server.createAccount \

     

       164
       164
       +
         -H "Content-Type: application/json" \

     

       165
       165
       +
         -d '{

     

       166
       166
       +
           "handle": "mynewsbot.bsky.social",

     

       167
       167
       +
           "email": "bot@example.com",

     

       168
       168
       +
           "password": "secure-password-here"

     

       169
       169
       +
         }'

     

       170
       170
       +
       ```

     

       171
       171
       +
       

     

       172
       172
       +
       **Response**:

     

       173
       173
       +
       ```json

     

       174
       174
       +
       {

     

       175
       175
       +
         "accessJwt": "eyJ...",

     

       176
       176
       +
         "refreshJwt": "eyJ...",

     

       177
       177
       +
         "handle": "mynewsbot.bsky.social",

     

       178
       178
       +
         "did": "did:plc:abc123...",

     

       179
       179
       +
         "didDoc": {...}

     

       180
       180
       +
       }

     

       181
       181
       +
       ```

     

       182
       182
       +
       

     

       183
       183
       +
       **Save these credentials securely!** You'll need the DID and access token for all subsequent operations.

     

       184
       184
       +
       

     

       185
       185
       +
       **Alternative**: Run your own PDS or use `did:web` (advanced).

     

       186
       186
       +
       

     

       187
       187
       +
       ### Step 2: Prove Domain Ownership

     

       188
       188
       +
       

     

       189
       189
       +
       To register with Coves, you must prove you own a domain by serving your DID at `https://yourdomain.com/.well-known/atproto-did`.

     

       190
       190
       +
       

     

       191
       191
       +
       **Create the file**:

     

       192
       192
       +
       

     

       193
       193
       +
       ```bash

     

       194
       194
       +
       mkdir -p .well-known

     

       195
       195
       +
       echo "did:plc:abc123..." > .well-known/atproto-did

     

       196
       196
       +
       ```

     

       197
       197
       +
       

     

       198
       198
       +
       **Upload to your web server** so it's accessible at:

     

       199
       199
       +
       ```

     

       200
       200
       +
       https://rss-bot.example.com/.well-known/atproto-did

     

       201
       201
       +
       ```

     

       202
       202
       +
       

     

       203
       203
       +
       **Verify it works**:

     

       204
       204
       +
       ```bash

     

       205
       205
       +
       curl https://rss-bot.example.com/.well-known/atproto-did

     

       206
       206
       +
       # Should return: did:plc:abc123...

     

       207
       207
       +
       ```

     

       208
       208
       +
       

     

       209
       209
       +
       **Nginx configuration example**:

     

       210
       210
       +
       ```nginx

     

       211
       211
       +
       location /.well-known/atproto-did {

     

       212
       212
       +
           alias /var/www/.well-known/atproto-did;

     

       213
       213
       +
           default_type text/plain;

     

       214
       214
       +
           add_header Access-Control-Allow-Origin *;

     

       215
       215
       +
       }

     

       216
       216
       +
       ```

     

       217
       217
       +
       

     

       218
       218
       +
       ### Step 3: Register with Coves

     

       219
       219
       +
       

     

       220
       220
       +
       Call the registration endpoint to register your aggregator DID with the Coves instance.

     

       221
       221
       +
       

     

       222
       222
       +
       **Endpoint**: `POST /xrpc/social.coves.aggregator.register`

     

       223
       223
       +
       

     

       224
       224
       +
       **Request**:

     

       225
       225
       +
       ```bash

     

       226
       226
       +
       curl -X POST https://api.coves.social/xrpc/social.coves.aggregator.register \

     

       227
       227
       +
         -H "Content-Type: application/json" \

     

       228
       228
       +
         -d '{

     

       229
       229
       +
           "did": "did:plc:abc123...",

     

       230
       230
       +
           "domain": "rss-bot.example.com"

     

       231
       231
       +
         }'

     

       232
       232
       +
       ```

     

       233
       233
       +
       

     

       234
       234
       +
       **Response** (Success):

     

       235
       235
       +
       ```json

     

       236
       236
       +
       {

     

       237
       237
       +
         "did": "did:plc:abc123...",

     

       238
       238
       +
         "handle": "mynewsbot.bsky.social",

     

       239
       239
       +
         "message": "Aggregator registered successfully. Next step: create a service declaration record at at://did:plc:abc123.../social.coves.aggregator.service/self"

     

       240
       240
       +
       }

     

       241
       241
       +
       ```

     

       242
       242
       +
       

     

       243
       243
       +
       **What happens**:

     

       244
       244
       +
       1. Coves fetches `https://rss-bot.example.com/.well-known/atproto-did`

     

       245
       245
       +
       2. Verifies it contains your DID

     

       246
       246
       +
       3. Resolves your DID to get handle and PDS URL

     

       247
       247
       +
       4. Inserts you into the `users` table

     

       248
       248
       +
       

     

       249
       249
       +
       **You're now registered!** But you need to create a service declaration next.

     

       250
       250
       +
       

     

       251
       251
       +
       ### Step 4: Create Service Declaration

     

       252
       252
       +
       

     

       253
       253
       +
       Write a `social.coves.aggregator.service` record to your repository. This contains metadata about your aggregator and gets indexed by Coves' Jetstream consumer.

     

       254
       254
       +
       

     

       255
       255
       +
       **Endpoint**: `POST https://your-pds.com/xrpc/com.atproto.repo.createRecord`

     

       256
       256
       +
       

     

       257
       257
       +
       **Request**:

     

       258
       258
       +
       ```bash

     

       259
       259
       +
       curl -X POST https://bsky.social/xrpc/com.atproto.repo.createRecord \

     

       260
       260
       +
         -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

     

       261
       261
       +
         -H "Content-Type: application/json" \

     

       262
       262
       +
         -d '{

     

       263
       263
       +
           "repo": "did:plc:abc123...",

     

       264
       264
       +
           "collection": "social.coves.aggregator.service",

     

       265
       265
       +
           "rkey": "self",

     

       266
       266
       +
           "record": {

     

       267
       267
       +
             "$type": "social.coves.aggregator.service",

     

       268
       268
       +
             "did": "did:plc:abc123...",

     

       269
       269
       +
             "displayName": "RSS News Aggregator",

     

       270
       270
       +
             "description": "Aggregates tech news from various RSS feeds",

     

       271
       271
       +
             "sourceUrl": "https://github.com/yourname/rss-aggregator",

     

       272
       272
       +
             "maintainer": "did:plc:your-personal-did",

     

       273
       273
       +
             "createdAt": "2024-01-15T12:00:00Z"

     

       274
       274
       +
           }

     

       275
       275
       +
         }'

     

       276
       276
       +
       ```

     

       277
       277
       +
       

     

       278
       278
       +
       **Response**:

     

       279
       279
       +
       ```json

     

       280
       280
       +
       {

     

       281
       281
       +
         "uri": "at://did:plc:abc123.../social.coves.aggregator.service/self",

     

       282
       282
       +
         "cid": "bafyrei..."

     

       283
       283
       +
       }

     

       284
       284
       +
       ```

     

       285
       285
       +
       

     

       286
       286
       +
       **Optional fields**:

     

       287
       287
       +
       - `avatar`: Blob reference to avatar image

     

       288
       288
       +
       - `configSchema`: JSON Schema for community-specific configuration

     

       289
       289
       +
       

     

       290
       290
       +
       **Wait 5-10 seconds** for Jetstream to index your service declaration into the `aggregators` table.

     

       291
       291
       +
       

     

       292
       292
       +
       ## Authorization Process

     

       293
       293
       +
       

     

       294
       294
       +
       Before you can post to a community, a moderator must authorize your aggregator.

     

       295
       295
       +
       

     

       296
       296
       +
       ### How Authorization Works

     

       297
       297
       +
       

     

       298
       298
       +
       1. **Moderator decision**: Community moderator evaluates your aggregator

     

       299
       299
       +
       2. **Authorization record**: Moderator writes `social.coves.aggregator.authorization` to community's repo

     

       300
       300
       +
       3. **Jetstream indexing**: Record gets indexed into `aggregator_authorizations` table

     

       301
       301
       +
       4. **Posting enabled**: You can now post to that community

     

       302
       302
       +
       

     

       303
       303
       +
       ### Authorization Record Structure

     

       304
       304
       +
       

     

       305
       305
       +
       **Location**: `at://{community_did}/social.coves.aggregator.authorization/{rkey}`

     

       306
       306
       +
       

     

       307
       307
       +
       **Example**:

     

       308
       308
       +
       ```json

     

       309
       309
       +
       {

     

       310
       310
       +
         "$type": "social.coves.aggregator.authorization",

     

       311
       311
       +
         "aggregatorDid": "did:plc:abc123...",

     

       312
       312
       +
         "communityDid": "did:plc:community123...",

     

       313
       313
       +
         "enabled": true,

     

       314
       314
       +
         "createdBy": "did:plc:moderator...",

     

       315
       315
       +
         "createdAt": "2024-01-15T12:00:00Z",

     

       316
       316
       +
         "config": {

     

       317
       317
       +
           "maxPostsPerHour": 5,

     

       318
       318
       +
           "allowedCategories": ["tech", "news"]

     

       319
       319
       +
         }

     

       320
       320
       +
       }

     

       321
       321
       +
       ```

     

       322
       322
       +
       

     

       323
       323
       +
       ### Checking Your Authorizations

     

       324
       324
       +
       

     

       325
       325
       +
       **Endpoint**: `GET /xrpc/social.coves.aggregator.getAuthorizations`

     

       326
       326
       +
       

     

       327
       327
       +
       ```bash

     

       328
       328
       +
       curl "https://api.coves.social/xrpc/social.coves.aggregator.getAuthorizations?aggregatorDid=did:plc:abc123...&enabledOnly=true"

     

       329
       329
       +
       ```

     

       330
       330
       +
       

     

       331
       331
       +
       **Response**:

     

       332
       332
       +
       ```json

     

       333
       333
       +
       {

     

       334
       334
       +
         "authorizations": [

     

       335
       335
       +
           {

     

       336
       336
       +
             "aggregatorDid": "did:plc:abc123...",

     

       337
       337
       +
             "communityDid": "did:plc:community123...",

     

       338
       338
       +
             "communityHandle": "~tech@coves.social",

     

       339
       339
       +
             "enabled": true,

     

       340
       340
       +
             "createdAt": "2024-01-15T12:00:00Z",

     

       341
       341
       +
             "config": {...}

     

       342
       342
       +
           }

     

       343
       343
       +
         ]

     

       344
       344
       +
       }

     

       345
       345
       +
       ```

     

       346
       346
       +
       

     

       347
       347
       +
       ## Posting to Communities

     

       348
       348
       +
       

     

       349
       349
       +
       Once authorized, you can post to communities using the standard post creation endpoint.

     

       350
       350
       +
       

     

       351
       351
       +
       ### Create Post

     

       352
       352
       +
       

     

       353
       353
       +
       **Endpoint**: `POST /xrpc/social.coves.community.post.create`

     

       354
       354
       +
       

     

       355
       355
       +
       **Request**:

     

       356
       356
       +
       ```bash

     

       357
       357
       +
       curl -X POST https://api.coves.social/xrpc/social.coves.community.post.create \

     

       358
       358
       +
         -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

     

       359
       359
       +
         -H "Content-Type: application/json" \

     

       360
       360
       +
         -d '{

     

       361
       361
       +
           "communityDid": "did:plc:community123...",

     

       362
       362
       +
           "post": {

     

       363
       363
       +
             "text": "New blog post: Understanding atProto Identity\nhttps://example.com/post",

     

       364
       364
       +
             "createdAt": "2024-01-15T12:00:00Z",

     

       365
       365
       +
             "facets": [

     

       366
       366
       +
               {

     

       367
       367
       +
                 "index": { "byteStart": 50, "byteEnd": 75 },

     

       368
       368
       +
                 "features": [

     

       369
       369
       +
                   {

     

       370
       370
       +
                     "$type": "social.coves.richtext.facet#link",

     

       371
       371
       +
                     "uri": "https://example.com/post"

     

       372
       372
       +
                   }

     

       373
       373
       +
                 ]

     

       374
       374
       +
               }

     

       375
       375
       +
             ]

     

       376
       376
       +
           }

     

       377
       377
       +
         }'

     

       378
       378
       +
       ```

     

       379
       379
       +
       

     

       380
       380
       +
       **Response**:

     

       381
       381
       +
       ```json

     

       382
       382
       +
       {

     

       383
       383
       +
         "uri": "at://did:plc:abc123.../social.coves.community.post/3k...",

     

       384
       384
       +
         "cid": "bafyrei..."

     

       385
       385
       +
       }

     

       386
       386
       +
       ```

     

       387
       387
       +
       

     

       388
       388
       +
       ### Post Validation

     

       389
       389
       +
       

     

       390
       390
       +
       The handler validates:

     

       391
       391
       +
       1. **Authentication**: Valid JWT token

     

       392
       392
       +
       2. **Author exists**: DID in `users` table

     

       393
       393
       +
       3. **Is aggregator**: DID in `aggregators` table

     

       394
       394
       +
       4. **Authorization**: Active authorization for (aggregator, community)

     

       395
       395
       +
       5. **Rate limit**: Less than 10 posts/hour to this community

     

       396
       396
       +
       6. **Content**: Valid post structure per lexicon

     

       397
       397
       +
       

     

       398
       398
       +
       ### Rate Limits

     

       399
       399
       +
       

     

       400
       400
       +
       **Per-community rate limit**: 10 posts per hour

     

       401
       401
       +
       

     

       402
       402
       +
       This is tracked in the `aggregator_posts` table and enforced at the handler level.

     

       403
       403
       +
       

     

       404
       404
       +
       **Why?**: Prevents spam while allowing useful bot activity.

     

       405
       405
       +
       

     

       406
       406
       +
       **Best practices**:

     

       407
       407
       +
       - Batch similar content

     

       408
       408
       +
       - Post only high-quality content

     

       409
       409
       +
       - Respect community guidelines

     

       410
       410
       +
       - Monitor your posting rate

     

       411
       411
       +
       

     

       412
       412
       +
       ## Security Best Practices

     

       413
       413
       +
       

     

       414
       414
       +
       ### Credential Management

     

       415
       415
       +
       

     

       416
       416
       +
       ✅ **DO**:

     

       417
       417
       +
       - Store credentials in environment variables or secret management

     

       418
       418
       +
       - Use HTTPS for all API calls

     

       419
       419
       +
       - Rotate access tokens regularly (use refresh tokens)

     

       420
       420
       +
       - Keep `aggregator-config.env` out of version control

     

       421
       421
       +
       

     

       422
       422
       +
       ❌ **DON'T**:

     

       423
       423
       +
       - Hardcode credentials in source code

     

       424
       424
       +
       - Commit credentials to Git

     

       425
       425
       +
       - Share access tokens publicly

     

       426
       426
       +
       - Reuse personal credentials for bots

     

       427
       427
       +
       

     

       428
       428
       +
       ### Domain Security

     

       429
       429
       +
       

     

       430
       430
       +
       ✅ **DO**:

     

       431
       431
       +
       - Use HTTPS for `.well-known` endpoint

     

       432
       432
       +
       - Keep domain under your control

     

       433
       433
       +
       - Monitor for unauthorized changes

     

       434
       434
       +
       - Use DNSSEC if possible

     

       435
       435
       +
       

     

       436
       436
       +
       ❌ **DON'T**:

     

       437
       437
       +
       - Use HTTP (will fail verification)

     

       438
       438
       +
       - Use shared/untrusted hosting

     

       439
       439
       +
       - Allow others to modify `.well-known` files

     

       440
       440
       +
       - Use expired SSL certificates

     

       441
       441
       +
       

     

       442
       442
       +
       ### Content Security

     

       443
       443
       +
       

     

       444
       444
       +
       ✅ **DO**:

     

       445
       445
       +
       - Validate all external content before posting

     

       446
       446
       +
       - Sanitize URLs and text

     

       447
       447
       +
       - Rate-limit your own posting

     

       448
       448
       +
       - Implement circuit breakers for failures

     

       449
       449
       +
       

     

       450
       450
       +
       ❌ **DON'T**:

     

       451
       451
       +
       - Post unvalidated user input

     

       452
       452
       +
       - Include malicious links

     

       453
       453
       +
       - Spam communities

     

       454
       454
       +
       - Bypass rate limits

     

       455
       455
       +
       

     

       456
       456
       +
       ## Troubleshooting

     

       457
       457
       +
       

     

       458
       458
       +
       ### Registration Errors

     

       459
       459
       +
       

     

       460
       460
       +
       #### Error: "DomainVerificationFailed"

     

       461
       461
       +
       

     

       462
       462
       +
       **Cause**: `.well-known/atproto-did` not accessible or contains wrong DID

     

       463
       463
       +
       

     

       464
       464
       +
       **Solutions**:

     

       465
       465
       +
       1. Verify file is accessible: `curl https://yourdomain.com/.well-known/atproto-did`

     

       466
       466
       +
       2. Check content matches your DID exactly (no extra whitespace)

     

       467
       467
       +
       3. Ensure HTTPS is working (not HTTP)

     

       468
       468
       +
       4. Check web server logs for access errors

     

       469
       469
       +
       5. Verify firewall rules allow HTTPS traffic

     

       470
       470
       +
       

     

       471
       471
       +
       #### Error: "AlreadyRegistered"

     

       472
       472
       +
       

     

       473
       473
       +
       **Cause**: This DID is already registered with this Coves instance

     

       474
       474
       +
       

     

       475
       475
       +
       **Solutions**:

     

       476
       476
       +
       - This is safe to ignore if you're re-running setup

     

       477
       477
       +
       - If you need to update info, just create a new service declaration

     

       478
       478
       +
       - Contact instance admin if you need to remove registration

     

       479
       479
       +
       

     

       480
       480
       +
       #### Error: "DIDResolutionFailed"

     

       481
       481
       +
       

     

       482
       482
       +
       **Cause**: Could not resolve DID document from PLC directory

     

       483
       483
       +
       

     

       484
       484
       +
       **Solutions**:

     

       485
       485
       +
       1. Verify DID exists: `curl https://plc.directory/{your-did}`

     

       486
       486
       +
       2. Wait 30 seconds and retry (PLC propagation delay)

     

       487
       487
       +
       3. Check PDS is accessible

     

       488
       488
       +
       4. Verify DID format is correct (must start with `did:plc:` or `did:web:`)

     

       489
       489
       +
       

     

       490
       490
       +
       ### Posting Errors

     

       491
       491
       +
       

     

       492
       492
       +
       #### Error: "NotAuthorized"

     

       493
       493
       +
       

     

       494
       494
       +
       **Cause**: No active authorization for this (aggregator, community) pair

     

       495
       495
       +
       

     

       496
       496
       +
       **Solutions**:

     

       497
       497
       +
       1. Check authorizations: `GET /xrpc/social.coves.aggregator.getAuthorizations`

     

       498
       498
       +
       2. Contact community moderator to request authorization

     

       499
       499
       +
       3. Verify authorization wasn't disabled

     

       500
       500
       +
       4. Wait for Jetstream to index authorization (5-10 seconds)

     

       501
       501
       +
       

     

       502
       502
       +
       #### Error: "RateLimitExceeded"

     

       503
       503
       +
       

     

       504
       504
       +
       **Cause**: Exceeded 10 posts/hour to this community

     

       505
       505
       +
       

     

       506
       506
       +
       **Solutions**:

     

       507
       507
       +
       1. Wait for the rate limit window to reset

     

       508
       508
       +
       2. Batch posts to stay under limit

     

       509
       509
       +
       3. Distribute posts across multiple communities

     

       510
       510
       +
       4. Implement posting queue in your aggregator

     

       511
       511
       +
       

     

       512
       512
       +
       ### Service Declaration Not Appearing

     

       513
       513
       +
       

     

       514
       514
       +
       **Symptoms**: Service declaration created but not in `aggregators` table

     

       515
       515
       +
       

     

       516
       516
       +
       **Solutions**:

     

       517
       517
       +
       1. Wait 5-10 seconds for Jetstream to index

     

       518
       518
       +
       2. Check Jetstream consumer logs for errors

     

       519
       519
       +
       3. Verify record was created: Check PDS at `at://your-did/social.coves.aggregator.service/self`

     

       520
       520
       +
       4. Verify `$type` field is exactly `"social.coves.aggregator.service"`

     

       521
       521
       +
       5. Check `displayName` is not empty (required field)

     

       522
       522
       +
       

     

       523
       523
       +
       ## API Reference

     

       524
       524
       +
       

     

       525
       525
       +
       ### Registration Endpoint

     

       526
       526
       +
       

     

       527
       527
       +
       **`POST /xrpc/social.coves.aggregator.register`**

     

       528
       528
       +
       

     

       529
       529
       +
       **Input**:

     

       530
       530
       +
       ```typescript

     

       531
       531
       +
       {

     

       532
       532
       +
         did: string      // DID of aggregator (did:plc or did:web)

     

       533
       533
       +
         domain: string   // Domain serving .well-known/atproto-did

     

       534
       534
       +
       }

     

       535
       535
       +
       ```

     

       536
       536
       +
       

     

       537
       537
       +
       **Output**:

     

       538
       538
       +
       ```typescript

     

       539
       539
       +
       {

     

       540
       540
       +
         did: string      // Registered DID

     

       541
       541
       +
         handle: string   // Handle from DID document

     

       542
       542
       +
         message: string  // Next steps message

     

       543
       543
       +
       }

     

       544
       544
       +
       ```

     

       545
       545
       +
       

     

       546
       546
       +
       **Errors**:

     

       547
       547
       +
       - `InvalidDID`: DID format invalid

     

       548
       548
       +
       - `DomainVerificationFailed`: .well-known verification failed

     

       549
       549
       +
       - `AlreadyRegistered`: DID already registered

     

       550
       550
       +
       - `DIDResolutionFailed`: Could not resolve DID

     

       551
       551
       +
       

     

       552
       552
       +
       ### Query Endpoints

     

       553
       553
       +
       

     

       554
       554
       +
       **`GET /xrpc/social.coves.aggregator.getServices`**

     

       555
       555
       +
       

     

       556
       556
       +
       Get aggregator service details.

     

       557
       557
       +
       

     

       558
       558
       +
       **Parameters**:

     

       559
       559
       +
       - `dids`: Array of DIDs (comma-separated)

     

       560
       560
       +
       

     

       561
       561
       +
       **`GET /xrpc/social.coves.aggregator.getAuthorizations`**

     

       562
       562
       +
       

     

       563
       563
       +
       List communities that authorized an aggregator.

     

       564
       564
       +
       

     

       565
       565
       +
       **Parameters**:

     

       566
       566
       +
       - `aggregatorDid`: Aggregator DID

     

       567
       567
       +
       - `enabledOnly`: Filter to enabled only (default: false)

     

       568
       568
       +
       

     

       569
       569
       +
       **`GET /xrpc/social.coves.aggregator.listForCommunity`**

     

       570
       570
       +
       

     

       571
       571
       +
       List aggregators authorized by a community.

     

       572
       572
       +
       

     

       573
       573
       +
       **Parameters**:

     

       574
       574
       +
       - `communityDid`: Community DID

     

       575
       575
       +
       - `enabledOnly`: Filter to enabled only (default: false)

     

       576
       576
       +
       

     

       577
       577
       +
       ## Further Reading

     

       578
       578
       +
       

     

       579
       579
       +
       - [Aggregator PRD](PRD_AGGREGATORS.md) - Architecture and design decisions

     

       580
       580
       +
       - [atProto Guide](../../ATPROTO_GUIDE.md) - atProto fundamentals

     

       581
       581
       +
       - [Communities PRD](../PRD_COMMUNITIES.md) - Community system overview

     

       582
       582
       +
       - [Setup Scripts README](../../scripts/aggregator-setup/README.md) - Script documentation

     

       583
       583
       +
       

     

       584
       584
       +
       ## Support

     

       585
       585
       +
       

     

       586
       586
       +
       For issues or questions:

     

       587
       587
       +
       

     

       588
       588
       +
       1. Check this guide's troubleshooting section

     

       589
       589
       +
       2. Review the PRD and architecture docs

     

       590
       590
       +
       3. Check Coves GitHub issues

     

       591
       591
       +
       4. Ask in Coves developer community

+95

scripts/aggregator-setup/1-create-pds-account.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       

     

       3
       3
       +
       # Script: 1-create-pds-account.sh

     

       4
       4
       +
       # Purpose: Create a PDS account for your aggregator

     

       5
       5
       +
       #

     

       6
       6
       +
       # This script helps you create an account on a PDS (Personal Data Server).

     

       7
       7
       +
       # The PDS will automatically create a DID:PLC for you.

     

       8
       8
       +
       

     

       9
       9
       +
       set -e

     

       10
       10
       +
       

     

       11
       11
       +
       echo "================================================"

     

       12
       12
       +
       echo "Step 1: Create PDS Account for Your Aggregator"

     

       13
       13
       +
       echo "================================================"

     

       14
       14
       +
       echo ""

     

       15
       15
       +
       

     

       16
       16
       +
       # Get PDS URL

     

       17
       17
       +
       read -p "Enter PDS URL (default: https://bsky.social): " PDS_URL

     

       18
       18
       +
       PDS_URL=${PDS_URL:-https://bsky.social}

     

       19
       19
       +
       

     

       20
       20
       +
       # Get credentials

     

       21
       21
       +
       read -p "Enter desired handle (e.g., mynewsbot.bsky.social): " HANDLE

     

       22
       22
       +
       read -p "Enter email: " EMAIL

     

       23
       23
       +
       read -sp "Enter password: " PASSWORD

     

       24
       24
       +
       echo ""

     

       25
       25
       +
       

     

       26
       26
       +
       # Validate inputs

     

       27
       27
       +
       if [ -z "$HANDLE" ] || [ -z "$EMAIL" ] || [ -z "$PASSWORD" ]; then

     

       28
       28
       +
           echo "Error: All fields are required"

     

       29
       29
       +
           exit 1

     

       30
       30
       +
       fi

     

       31
       31
       +
       

     

       32
       32
       +
       echo ""

     

       33
       33
       +
       echo "Creating account on $PDS_URL..."

     

       34
       34
       +
       

     

       35
       35
       +
       # Create account via com.atproto.server.createAccount

     

       36
       36
       +
       RESPONSE=$(curl -s -X POST "$PDS_URL/xrpc/com.atproto.server.createAccount" \

     

       37
       37
       +
           -H "Content-Type: application/json" \

     

       38
       38
       +
           -d "{

     

       39
       39
       +
               \"handle\": \"$HANDLE\",

     

       40
       40
       +
               \"email\": \"$EMAIL\",

     

       41
       41
       +
               \"password\": \"$PASSWORD\"

     

       42
       42
       +
           }")

     

       43
       43
       +
       

     

       44
       44
       +
       # Check if successful

     

       45
       45
       +
       if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       46
       46
       +
           echo "Error creating account:"

     

       47
       47
       +
           echo "$RESPONSE" | jq '.'

     

       48
       48
       +
           exit 1

     

       49
       49
       +
       fi

     

       50
       50
       +
       

     

       51
       51
       +
       # Extract DID and access token

     

       52
       52
       +
       DID=$(echo "$RESPONSE" | jq -r '.did')

     

       53
       53
       +
       ACCESS_JWT=$(echo "$RESPONSE" | jq -r '.accessJwt')

     

       54
       54
       +
       REFRESH_JWT=$(echo "$RESPONSE" | jq -r '.refreshJwt')

     

       55
       55
       +
       

     

       56
       56
       +
       if [ -z "$DID" ] || [ "$DID" = "null" ]; then

     

       57
       57
       +
           echo "Error: Failed to extract DID from response"

     

       58
       58
       +
           echo "$RESPONSE" | jq '.'

     

       59
       59
       +
           exit 1

     

       60
       60
       +
       fi

     

       61
       61
       +
       

     

       62
       62
       +
       echo ""

     

       63
       63
       +
       echo "✓ Account created successfully!"

     

       64
       64
       +
       echo ""

     

       65
       65
       +
       echo "=== Save these credentials ===="

     

       66
       66
       +
       echo "DID:          $DID"

     

       67
       67
       +
       echo "Handle:       $HANDLE"

     

       68
       68
       +
       echo "PDS URL:      $PDS_URL"

     

       69
       69
       +
       echo "Email:        $EMAIL"

     

       70
       70
       +
       echo "Password:     [hidden]"

     

       71
       71
       +
       echo "Access JWT:   $ACCESS_JWT"

     

       72
       72
       +
       echo "Refresh JWT:  $REFRESH_JWT"

     

       73
       73
       +
       echo "==============================="

     

       74
       74
       +
       echo ""

     

       75
       75
       +
       

     

       76
       76
       +
       # Save to config file

     

       77
       77
       +
       CONFIG_FILE="aggregator-config.env"

     

       78
       78
       +
       cat > "$CONFIG_FILE" <<EOF

     

       79
       79
       +
       # Aggregator Account Configuration

     

       80
       80
       +
       # Generated: $(date)

     

       81
       81
       +
       

     

       82
       82
       +
       AGGREGATOR_DID="$DID"

     

       83
       83
       +
       AGGREGATOR_HANDLE="$HANDLE"

     

       84
       84
       +
       AGGREGATOR_PDS_URL="$PDS_URL"

     

       85
       85
       +
       AGGREGATOR_EMAIL="$EMAIL"

     

       86
       86
       +
       AGGREGATOR_PASSWORD="$PASSWORD"

     

       87
       87
       +
       AGGREGATOR_ACCESS_JWT="$ACCESS_JWT"

     

       88
       88
       +
       AGGREGATOR_REFRESH_JWT="$REFRESH_JWT"

     

       89
       89
       +
       EOF

     

       90
       90
       +
       

     

       91
       91
       +
       echo "✓ Configuration saved to $CONFIG_FILE"

     

       92
       92
       +
       echo ""

     

       93
       93
       +
       echo "IMPORTANT: Keep this file secure! It contains your credentials."

     

       94
       94
       +
       echo ""

     

       95
       95
       +
       echo "Next step: Run ./2-setup-wellknown.sh"

+93

scripts/aggregator-setup/2-setup-wellknown.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       

     

       3
       3
       +
       # Script: 2-setup-wellknown.sh

     

       4
       4
       +
       # Purpose: Generate .well-known/atproto-did file for domain verification

     

       5
       5
       +
       #

     

       6
       6
       +
       # This script creates the .well-known/atproto-did file that proves you own your domain.

     

       7
       7
       +
       # You'll need to host this file at https://yourdomain.com/.well-known/atproto-did

     

       8
       8
       +
       

     

       9
       9
       +
       set -e

     

       10
       10
       +
       

     

       11
       11
       +
       echo "================================================"

     

       12
       12
       +
       echo "Step 2: Setup .well-known/atproto-did"

     

       13
       13
       +
       echo "================================================"

     

       14
       14
       +
       echo ""

     

       15
       15
       +
       

     

       16
       16
       +
       # Load config if available

     

       17
       17
       +
       if [ -f "aggregator-config.env" ]; then

     

       18
       18
       +
           source aggregator-config.env

     

       19
       19
       +
           echo "✓ Loaded configuration from aggregator-config.env"

     

       20
       20
       +
           echo "  DID: $AGGREGATOR_DID"

     

       21
       21
       +
           echo ""

     

       22
       22
       +
       else

     

       23
       23
       +
           echo "Configuration file not found. Please run 1-create-pds-account.sh first."

     

       24
       24
       +
           exit 1

     

       25
       25
       +
       fi

     

       26
       26
       +
       

     

       27
       27
       +
       # Get domain

     

       28
       28
       +
       read -p "Enter your aggregator's domain (e.g., rss-bot.example.com): " DOMAIN

     

       29
       29
       +
       

     

       30
       30
       +
       if [ -z "$DOMAIN" ]; then

     

       31
       31
       +
           echo "Error: Domain is required"

     

       32
       32
       +
           exit 1

     

       33
       33
       +
       fi

     

       34
       34
       +
       

     

       35
       35
       +
       # Save domain to config

     

       36
       36
       +
       echo "" >> aggregator-config.env

     

       37
       37
       +
       echo "AGGREGATOR_DOMAIN=\"$DOMAIN\"" >> aggregator-config.env

     

       38
       38
       +
       

     

       39
       39
       +
       echo ""

     

       40
       40
       +
       echo "Creating .well-known directory..."

     

       41
       41
       +
       mkdir -p .well-known

     

       42
       42
       +
       

     

       43
       43
       +
       # Create the atproto-did file

     

       44
       44
       +
       echo "$AGGREGATOR_DID" > .well-known/atproto-did

     

       45
       45
       +
       

     

       46
       46
       +
       echo "✓ Created .well-known/atproto-did with content: $AGGREGATOR_DID"

     

       47
       47
       +
       echo ""

     

       48
       48
       +
       

     

       49
       49
       +
       echo "================================================"

     

       50
       50
       +
       echo "Next Steps:"

     

       51
       51
       +
       echo "================================================"

     

       52
       52
       +
       echo ""

     

       53
       53
       +
       echo "1. Upload the .well-known directory to your web server"

     

       54
       54
       +
       echo "   The file must be accessible at:"

     

       55
       55
       +
       echo "   https://$DOMAIN/.well-known/atproto-did"

     

       56
       56
       +
       echo ""

     

       57
       57
       +
       echo "2. Verify it's working by running:"

     

       58
       58
       +
       echo "   curl https://$DOMAIN/.well-known/atproto-did"

     

       59
       59
       +
       echo "   (Should return: $AGGREGATOR_DID)"

     

       60
       60
       +
       echo ""

     

       61
       61
       +
       echo "3. Once verified, run: ./3-register-with-coves.sh"

     

       62
       62
       +
       echo ""

     

       63
       63
       +
       

     

       64
       64
       +
       # Create nginx example

     

       65
       65
       +
       cat > nginx-example.conf <<EOF

     

       66
       66
       +
       # Example nginx configuration for serving .well-known

     

       67
       67
       +
       # Add this to your nginx server block:

     

       68
       68
       +
       

     

       69
       69
       +
       location /.well-known/atproto-did {

     

       70
       70
       +
           alias /path/to/your/.well-known/atproto-did;

     

       71
       71
       +
           default_type text/plain;

     

       72
       72
       +
           add_header Access-Control-Allow-Origin *;

     

       73
       73
       +
       }

     

       74
       74
       +
       EOF

     

       75
       75
       +
       

     

       76
       76
       +
       echo "✓ Created nginx-example.conf for reference"

     

       77
       77
       +
       echo ""

     

       78
       78
       +
       

     

       79
       79
       +
       # Create Apache example

     

       80
       80
       +
       cat > apache-example.conf <<EOF

     

       81
       81
       +
       # Example Apache configuration for serving .well-known

     

       82
       82
       +
       # Add this to your Apache virtual host:

     

       83
       83
       +
       

     

       84
       84
       +
       Alias /.well-known /path/to/your/.well-known

     

       85
       85
       +
       <Directory /path/to/your/.well-known>

     

       86
       86
       +
           Options None

     

       87
       87
       +
           AllowOverride None

     

       88
       88
       +
           Require all granted

     

       89
       89
       +
           Header set Access-Control-Allow-Origin "*"

     

       90
       90
       +
       </Directory>

     

       91
       91
       +
       EOF

     

       92
       92
       +
       

     

       93
       93
       +
       echo "✓ Created apache-example.conf for reference"

+103

scripts/aggregator-setup/3-register-with-coves.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       

     

       3
       3
       +
       # Script: 3-register-with-coves.sh

     

       4
       4
       +
       # Purpose: Register your aggregator with a Coves instance

     

       5
       5
       +
       #

     

       6
       6
       +
       # This script calls the social.coves.aggregator.register XRPC endpoint

     

       7
       7
       +
       # to register your aggregator DID with the Coves instance.

     

       8
       8
       +
       

     

       9
       9
       +
       set -e

     

       10
       10
       +
       

     

       11
       11
       +
       echo "================================================"

     

       12
       12
       +
       echo "Step 3: Register with Coves Instance"

     

       13
       13
       +
       echo "================================================"

     

       14
       14
       +
       echo ""

     

       15
       15
       +
       

     

       16
       16
       +
       # Load config if available

     

       17
       17
       +
       if [ -f "aggregator-config.env" ]; then

     

       18
       18
       +
           source aggregator-config.env

     

       19
       19
       +
           echo "✓ Loaded configuration from aggregator-config.env"

     

       20
       20
       +
           echo "  DID:    $AGGREGATOR_DID"

     

       21
       21
       +
           echo "  Domain: $AGGREGATOR_DOMAIN"

     

       22
       22
       +
           echo ""

     

       23
       23
       +
       else

     

       24
       24
       +
           echo "Configuration file not found. Please run previous scripts first."

     

       25
       25
       +
           exit 1

     

       26
       26
       +
       fi

     

       27
       27
       +
       

     

       28
       28
       +
       # Validate domain is set

     

       29
       29
       +
       if [ -z "$AGGREGATOR_DOMAIN" ]; then

     

       30
       30
       +
           echo "Error: AGGREGATOR_DOMAIN not set. Please run 2-setup-wellknown.sh first."

     

       31
       31
       +
           exit 1

     

       32
       32
       +
       fi

     

       33
       33
       +
       

     

       34
       34
       +
       # Get Coves instance URL

     

       35
       35
       +
       read -p "Enter Coves instance URL (default: https://api.coves.social): " COVES_URL

     

       36
       36
       +
       COVES_URL=${COVES_URL:-https://api.coves.social}

     

       37
       37
       +
       

     

       38
       38
       +
       echo ""

     

       39
       39
       +
       echo "Verifying .well-known/atproto-did is accessible..."

     

       40
       40
       +
       

     

       41
       41
       +
       # Verify .well-known is accessible

     

       42
       42
       +
       WELLKNOWN_URL="https://$AGGREGATOR_DOMAIN/.well-known/atproto-did"

     

       43
       43
       +
       WELLKNOWN_CONTENT=$(curl -s "$WELLKNOWN_URL" || echo "ERROR")

     

       44
       44
       +
       

     

       45
       45
       +
       if [ "$WELLKNOWN_CONTENT" = "ERROR" ]; then

     

       46
       46
       +
           echo "✗ Error: Could not access $WELLKNOWN_URL"

     

       47
       47
       +
           echo "  Please ensure the file is uploaded and accessible."

     

       48
       48
       +
           exit 1

     

       49
       49
       +
       elif [ "$WELLKNOWN_CONTENT" != "$AGGREGATOR_DID" ]; then

     

       50
       50
       +
           echo "✗ Error: .well-known/atproto-did contains wrong DID"

     

       51
       51
       +
           echo "  Expected: $AGGREGATOR_DID"

     

       52
       52
       +
           echo "  Got:      $WELLKNOWN_CONTENT"

     

       53
       53
       +
           exit 1

     

       54
       54
       +
       fi

     

       55
       55
       +
       

     

       56
       56
       +
       echo "✓ .well-known/atproto-did is correctly configured"

     

       57
       57
       +
       echo ""

     

       58
       58
       +
       

     

       59
       59
       +
       echo "Registering with $COVES_URL..."

     

       60
       60
       +
       

     

       61
       61
       +
       # Call registration endpoint

     

       62
       62
       +
       RESPONSE=$(curl -s -X POST "$COVES_URL/xrpc/social.coves.aggregator.register" \

     

       63
       63
       +
           -H "Content-Type: application/json" \

     

       64
       64
       +
           -d "{

     

       65
       65
       +
               \"did\": \"$AGGREGATOR_DID\",

     

       66
       66
       +
               \"domain\": \"$AGGREGATOR_DOMAIN\"

     

       67
       67
       +
           }")

     

       68
       68
       +
       

     

       69
       69
       +
       # Check if successful

     

       70
       70
       +
       if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       71
       71
       +
           echo "✗ Registration failed:"

     

       72
       72
       +
           echo "$RESPONSE" | jq '.'

     

       73
       73
       +
           exit 1

     

       74
       74
       +
       fi

     

       75
       75
       +
       

     

       76
       76
       +
       # Extract response

     

       77
       77
       +
       REGISTERED_DID=$(echo "$RESPONSE" | jq -r '.did')

     

       78
       78
       +
       REGISTERED_HANDLE=$(echo "$RESPONSE" | jq -r '.handle')

     

       79
       79
       +
       MESSAGE=$(echo "$RESPONSE" | jq -r '.message')

     

       80
       80
       +
       

     

       81
       81
       +
       if [ -z "$REGISTERED_DID" ] || [ "$REGISTERED_DID" = "null" ]; then

     

       82
       82
       +
           echo "✗ Error: Unexpected response format"

     

       83
       83
       +
           echo "$RESPONSE" | jq '.'

     

       84
       84
       +
           exit 1

     

       85
       85
       +
       fi

     

       86
       86
       +
       

     

       87
       87
       +
       echo ""

     

       88
       88
       +
       echo "✓ Registration successful!"

     

       89
       89
       +
       echo ""

     

       90
       90
       +
       echo "=== Registration Details ===="

     

       91
       91
       +
       echo "DID:     $REGISTERED_DID"

     

       92
       92
       +
       echo "Handle:  $REGISTERED_HANDLE"

     

       93
       93
       +
       echo "Message: $MESSAGE"

     

       94
       94
       +
       echo "============================="

     

       95
       95
       +
       echo ""

     

       96
       96
       +
       

     

       97
       97
       +
       # Save Coves URL to config

     

       98
       98
       +
       echo "" >> aggregator-config.env

     

       99
       99
       +
       echo "COVES_INSTANCE_URL=\"$COVES_URL\"" >> aggregator-config.env

     

       100
       100
       +
       

     

       101
       101
       +
       echo "✓ Updated aggregator-config.env with Coves instance URL"

     

       102
       102
       +
       echo ""

     

       103
       103
       +
       echo "Next step: Run ./4-create-service-declaration.sh"

+125

scripts/aggregator-setup/4-create-service-declaration.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       

     

       3
       3
       +
       # Script: 4-create-service-declaration.sh

     

       4
       4
       +
       # Purpose: Create aggregator service declaration record

     

       5
       5
       +
       #

     

       6
       6
       +
       # This script writes a social.coves.aggregator.service record to your aggregator's repository.

     

       7
       7
       +
       # This record contains metadata about your aggregator (name, description, etc.) and will be

     

       8
       8
       +
       # indexed by Coves' Jetstream consumer into the aggregators table.

     

       9
       9
       +
       

     

       10
       10
       +
       set -e

     

       11
       11
       +
       

     

       12
       12
       +
       echo "================================================"

     

       13
       13
       +
       echo "Step 4: Create Service Declaration"

     

       14
       14
       +
       echo "================================================"

     

       15
       15
       +
       echo ""

     

       16
       16
       +
       

     

       17
       17
       +
       # Load config if available

     

       18
       18
       +
       if [ -f "aggregator-config.env" ]; then

     

       19
       19
       +
           source aggregator-config.env

     

       20
       20
       +
           echo "✓ Loaded configuration from aggregator-config.env"

     

       21
       21
       +
           echo "  DID:       $AGGREGATOR_DID"

     

       22
       22
       +
           echo "  PDS URL:   $AGGREGATOR_PDS_URL"

     

       23
       23
       +
           echo ""

     

       24
       24
       +
       else

     

       25
       25
       +
           echo "Configuration file not found. Please run previous scripts first."

     

       26
       26
       +
           exit 1

     

       27
       27
       +
       fi

     

       28
       28
       +
       

     

       29
       29
       +
       # Validate required fields

     

       30
       30
       +
       if [ -z "$AGGREGATOR_ACCESS_JWT" ]; then

     

       31
       31
       +
           echo "Error: AGGREGATOR_ACCESS_JWT not set. Please run 1-create-pds-account.sh first."

     

       32
       32
       +
           exit 1

     

       33
       33
       +
       fi

     

       34
       34
       +
       

     

       35
       35
       +
       echo "Enter aggregator metadata:"

     

       36
       36
       +
       echo ""

     

       37
       37
       +
       

     

       38
       38
       +
       # Get metadata from user

     

       39
       39
       +
       read -p "Display Name (e.g., 'RSS News Aggregator'): " DISPLAY_NAME

     

       40
       40
       +
       read -p "Description: " DESCRIPTION

     

       41
       41
       +
       read -p "Source URL (e.g., 'https://github.com/yourname/aggregator'): " SOURCE_URL

     

       42
       42
       +
       read -p "Maintainer DID (your personal DID, optional): " MAINTAINER_DID

     

       43
       43
       +
       

     

       44
       44
       +
       if [ -z "$DISPLAY_NAME" ]; then

     

       45
       45
       +
           echo "Error: Display name is required"

     

       46
       46
       +
           exit 1

     

       47
       47
       +
       fi

     

       48
       48
       +
       

     

       49
       49
       +
       echo ""

     

       50
       50
       +
       echo "Creating service declaration record..."

     

       51
       51
       +
       

     

       52
       52
       +
       # Build the service record

     

       53
       53
       +
       SERVICE_RECORD=$(cat <<EOF

     

       54
       54
       +
       {

     

       55
       55
       +
           "\$type": "social.coves.aggregator.service",

     

       56
       56
       +
           "did": "$AGGREGATOR_DID",

     

       57
       57
       +
           "displayName": "$DISPLAY_NAME",

     

       58
       58
       +
           "description": "$DESCRIPTION",

     

       59
       59
       +
           "sourceUrl": "$SOURCE_URL",

     

       60
       60
       +
           "maintainer": "$MAINTAINER_DID",

     

       61
       61
       +
           "createdAt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"

     

       62
       62
       +
       }

     

       63
       63
       +
       EOF

     

       64
       64
       +
       )

     

       65
       65
       +
       

     

       66
       66
       +
       # Call com.atproto.repo.createRecord

     

       67
       67
       +
       RESPONSE=$(curl -s -X POST "$AGGREGATOR_PDS_URL/xrpc/com.atproto.repo.createRecord" \

     

       68
       68
       +
           -H "Authorization: Bearer $AGGREGATOR_ACCESS_JWT" \

     

       69
       69
       +
           -H "Content-Type: application/json" \

     

       70
       70
       +
           -d "{

     

       71
       71
       +
               \"repo\": \"$AGGREGATOR_DID\",

     

       72
       72
       +
               \"collection\": \"social.coves.aggregator.service\",

     

       73
       73
       +
               \"rkey\": \"self\",

     

       74
       74
       +
               \"record\": $SERVICE_RECORD

     

       75
       75
       +
           }")

     

       76
       76
       +
       

     

       77
       77
       +
       # Check if successful

     

       78
       78
       +
       if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       79
       79
       +
           echo "✗ Failed to create service declaration:"

     

       80
       80
       +
           echo "$RESPONSE" | jq '.'

     

       81
       81
       +
           exit 1

     

       82
       82
       +
       fi

     

       83
       83
       +
       

     

       84
       84
       +
       # Extract response

     

       85
       85
       +
       RECORD_URI=$(echo "$RESPONSE" | jq -r '.uri')

     

       86
       86
       +
       RECORD_CID=$(echo "$RESPONSE" | jq -r '.cid')

     

       87
       87
       +
       

     

       88
       88
       +
       if [ -z "$RECORD_URI" ] || [ "$RECORD_URI" = "null" ]; then

     

       89
       89
       +
           echo "✗ Error: Unexpected response format"

     

       90
       90
       +
           echo "$RESPONSE" | jq '.'

     

       91
       91
       +
           exit 1

     

       92
       92
       +
       fi

     

       93
       93
       +
       

     

       94
       94
       +
       echo ""

     

       95
       95
       +
       echo "✓ Service declaration created successfully!"

     

       96
       96
       +
       echo ""

     

       97
       97
       +
       echo "=== Record Details ===="

     

       98
       98
       +
       echo "URI: $RECORD_URI"

     

       99
       99
       +
       echo "CID: $RECORD_CID"

     

       100
       100
       +
       echo "======================="

     

       101
       101
       +
       echo ""

     

       102
       102
       +
       

     

       103
       103
       +
       # Save to config

     

       104
       104
       +
       echo "" >> aggregator-config.env

     

       105
       105
       +
       echo "SERVICE_DECLARATION_URI=\"$RECORD_URI\"" >> aggregator-config.env

     

       106
       106
       +
       echo "SERVICE_DECLARATION_CID=\"$RECORD_CID\"" >> aggregator-config.env

     

       107
       107
       +
       

     

       108
       108
       +
       echo "✓ Updated aggregator-config.env"

     

       109
       109
       +
       echo ""

     

       110
       110
       +
       echo "================================================"

     

       111
       111
       +
       echo "Setup Complete!"

     

       112
       112
       +
       echo "================================================"

     

       113
       113
       +
       echo ""

     

       114
       114
       +
       echo "Your aggregator is now registered with Coves!"

     

       115
       115
       +
       echo ""

     

       116
       116
       +
       echo "Next steps:"

     

       117
       117
       +
       echo "1. Wait a few seconds for Jetstream to index your service declaration"

     

       118
       118
       +
       echo "2. Verify your aggregator appears in the aggregators list"

     

       119
       119
       +
       echo "3. Community moderators can now authorize your aggregator"

     

       120
       120
       +
       echo "4. Once authorized, you can start posting to communities"

     

       121
       121
       +
       echo ""

     

       122
       122
       +
       echo "To test posting, use the Coves XRPC endpoint:"

     

       123
       123
       +
       echo "  POST $COVES_INSTANCE_URL/xrpc/social.coves.community.post.create"

     

       124
       124
       +
       echo ""

     

       125
       125
       +
       echo "See docs/aggregators/SETUP_GUIDE.md for more information"

+252

scripts/aggregator-setup/README.md

···

       1
       1
       +
       # Aggregator Setup Scripts

     

       2
       2
       +
       

     

       3
       3
       +
       This directory contains scripts to help you set up and register your aggregator with Coves instances.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Overview

     

       6
       6
       +
       

     

       7
       7
       +
       Aggregators are automated services that post content to Coves communities. They are similar to Bluesky's feed generators and labelers. To use aggregators with Coves, you need to:

     

       8
       8
       +
       

     

       9
       9
       +
       1. Create a PDS account for your aggregator (gets you a DID)

     

       10
       10
       +
       2. Prove you own a domain via `.well-known/atproto-did`

     

       11
       11
       +
       3. Register with a Coves instance

     

       12
       12
       +
       4. Create a service declaration record

     

       13
       13
       +
       

     

       14
       14
       +
       These scripts automate this process for you.

     

       15
       15
       +
       

     

       16
       16
       +
       ## Prerequisites

     

       17
       17
       +
       

     

       18
       18
       +
       - **Domain ownership**: You must own a domain where you can host the `.well-known/atproto-did` file

     

       19
       19
       +
       - **Web server**: Ability to serve static files over HTTPS

     

       20
       20
       +
       - **Tools**: `curl`, `jq` (for JSON processing)

     

       21
       21
       +
       - **Account**: Email address for creating the PDS account

     

       22
       22
       +
       

     

       23
       23
       +
       ## Quick Start

     

       24
       24
       +
       

     

       25
       25
       +
       ### Interactive Setup (Recommended)

     

       26
       26
       +
       

     

       27
       27
       +
       Run the scripts in order:

     

       28
       28
       +
       

     

       29
       29
       +
       ```bash

     

       30
       30
       +
       # Make scripts executable

     

       31
       31
       +
       chmod +x *.sh

     

       32
       32
       +
       

     

       33
       33
       +
       # Step 1: Create PDS account

     

       34
       34
       +
       ./1-create-pds-account.sh

     

       35
       35
       +
       

     

       36
       36
       +
       # Step 2: Generate .well-known file

     

       37
       37
       +
       ./2-setup-wellknown.sh

     

       38
       38
       +
       

     

       39
       39
       +
       # Step 3: Register with Coves (after uploading .well-known)

     

       40
       40
       +
       ./3-register-with-coves.sh

     

       41
       41
       +
       

     

       42
       42
       +
       # Step 4: Create service declaration

     

       43
       43
       +
       ./4-create-service-declaration.sh

     

       44
       44
       +
       ```

     

       45
       45
       +
       

     

       46
       46
       +
       ### Automated Setup Example

     

       47
       47
       +
       

     

       48
       48
       +
       For a reference implementation of automated setup, see the Kagi News aggregator at [aggregators/kagi-news/scripts/setup.sh](../../aggregators/kagi-news/scripts/setup.sh).

     

       49
       49
       +
       

     

       50
       50
       +
       The Kagi script shows how to automate all 4 steps (with the manual .well-known upload step in between).

     

       51
       51
       +
       

     

       52
       52
       +
       ## Script Reference

     

       53
       53
       +
       

     

       54
       54
       +
       ### 1-create-pds-account.sh

     

       55
       55
       +
       

     

       56
       56
       +
       **Purpose**: Creates a PDS account for your aggregator

     

       57
       57
       +
       

     

       58
       58
       +
       **Prompts for**:

     

       59
       59
       +
       - PDS URL (default: https://bsky.social)

     

       60
       60
       +
       - Handle (e.g., mynewsbot.bsky.social)

     

       61
       61
       +
       - Email

     

       62
       62
       +
       - Password

     

       63
       63
       +
       

     

       64
       64
       +
       **Outputs**:

     

       65
       65
       +
       - `aggregator-config.env` - Configuration file with DID and credentials

     

       66
       66
       +
       - Prints your DID and access tokens

     

       67
       67
       +
       

     

       68
       68
       +
       **Notes**:

     

       69
       69
       +
       - Keep the config file secure! It contains your credentials

     

       70
       70
       +
       - The PDS automatically generates a DID:PLC for you

     

       71
       71
       +
       - You can use any PDS service, not just bsky.social

     

       72
       72
       +
       

     

       73
       73
       +
       ### 2-setup-wellknown.sh

     

       74
       74
       +
       

     

       75
       75
       +
       **Purpose**: Generates the `.well-known/atproto-did` file for domain verification

     

       76
       76
       +
       

     

       77
       77
       +
       **Prompts for**:

     

       78
       78
       +
       - Your domain (e.g., rss-bot.example.com)

     

       79
       79
       +
       

     

       80
       80
       +
       **Outputs**:

     

       81
       81
       +
       - `.well-known/atproto-did` - File containing your DID

     

       82
       82
       +
       - `nginx-example.conf` - Example nginx configuration

     

       83
       83
       +
       - `apache-example.conf` - Example Apache configuration

     

       84
       84
       +
       

     

       85
       85
       +
       **Manual step required**:

     

       86
       86
       +
       Upload the `.well-known` directory to your web server. The file must be accessible at:

     

       87
       87
       +
       ```

     

       88
       88
       +
       https://yourdomain.com/.well-known/atproto-did

     

       89
       89
       +
       ```

     

       90
       90
       +
       

     

       91
       91
       +
       **Verify it works**:

     

       92
       92
       +
       ```bash

     

       93
       93
       +
       curl https://yourdomain.com/.well-known/atproto-did

     

       94
       94
       +
       # Should return your DID (e.g., did:plc:abc123...)

     

       95
       95
       +
       ```

     

       96
       96
       +
       

     

       97
       97
       +
       ### 3-register-with-coves.sh

     

       98
       98
       +
       

     

       99
       99
       +
       **Purpose**: Registers your aggregator with a Coves instance

     

       100
       100
       +
       

     

       101
       101
       +
       **Prompts for**:

     

       102
       102
       +
       - Coves instance URL (default: https://api.coves.social)

     

       103
       103
       +
       

     

       104
       104
       +
       **Prerequisites**:

     

       105
       105
       +
       - `.well-known/atproto-did` must be accessible from your domain

     

       106
       106
       +
       - Scripts 1 and 2 must be completed

     

       107
       107
       +
       

     

       108
       108
       +
       **What it does**:

     

       109
       109
       +
       1. Verifies your `.well-known/atproto-did` is accessible

     

       110
       110
       +
       2. Calls `social.coves.aggregator.register` XRPC endpoint

     

       111
       111
       +
       3. Coves verifies domain ownership

     

       112
       112
       +
       4. Inserts your aggregator into the `users` table

     

       113
       113
       +
       

     

       114
       114
       +
       **Outputs**:

     

       115
       115
       +
       - Updates `aggregator-config.env` with Coves instance URL

     

       116
       116
       +
       - Prints registration confirmation

     

       117
       117
       +
       

     

       118
       118
       +
       ### 4-create-service-declaration.sh

     

       119
       119
       +
       

     

       120
       120
       +
       **Purpose**: Creates the service declaration record in your repository

     

       121
       121
       +
       

     

       122
       122
       +
       **Prompts for**:

     

       123
       123
       +
       - Display name (e.g., "RSS News Aggregator")

     

       124
       124
       +
       - Description

     

       125
       125
       +
       - Source URL (GitHub repo, etc.)

     

       126
       126
       +
       - Maintainer DID (optional)

     

       127
       127
       +
       

     

       128
       128
       +
       **What it does**:

     

       129
       129
       +
       1. Creates a `social.coves.aggregator.service` record at `at://your-did/social.coves.aggregator.service/self`

     

       130
       130
       +
       2. Jetstream consumer will index this into the `aggregators` table

     

       131
       131
       +
       3. Communities can now discover and authorize your aggregator

     

       132
       132
       +
       

     

       133
       133
       +
       **Outputs**:

     

       134
       134
       +
       - Updates `aggregator-config.env` with record URI and CID

     

       135
       135
       +
       - Prints record details

     

       136
       136
       +
       

     

       137
       137
       +
       ## Configuration File

     

       138
       138
       +
       

     

       139
       139
       +
       After running the scripts, you'll have an `aggregator-config.env` file with:

     

       140
       140
       +
       

     

       141
       141
       +
       ```bash

     

       142
       142
       +
       AGGREGATOR_DID="did:plc:..."

     

       143
       143
       +
       AGGREGATOR_HANDLE="mynewsbot.bsky.social"

     

       144
       144
       +
       AGGREGATOR_PDS_URL="https://bsky.social"

     

       145
       145
       +
       AGGREGATOR_EMAIL="bot@example.com"

     

       146
       146
       +
       AGGREGATOR_PASSWORD="..."

     

       147
       147
       +
       AGGREGATOR_ACCESS_JWT="..."

     

       148
       148
       +
       AGGREGATOR_REFRESH_JWT="..."

     

       149
       149
       +
       AGGREGATOR_DOMAIN="rss-bot.example.com"

     

       150
       150
       +
       COVES_INSTANCE_URL="https://api.coves.social"

     

       151
       151
       +
       SERVICE_DECLARATION_URI="at://did:plc:.../social.coves.aggregator.service/self"

     

       152
       152
       +
       SERVICE_DECLARATION_CID="..."

     

       153
       153
       +
       ```

     

       154
       154
       +
       

     

       155
       155
       +
       **Use this in your aggregator code** to authenticate and post.

     

       156
       156
       +
       

     

       157
       157
       +
       ## What Happens Next?

     

       158
       158
       +
       

     

       159
       159
       +
       After completing all 4 steps:

     

       160
       160
       +
       

     

       161
       161
       +
       1. **Your aggregator is registered** in the Coves instance's `users` table

     

       162
       162
       +
       2. **Your service declaration is indexed** in the `aggregators` table (takes a few seconds)

     

       163
       163
       +
       3. **Community moderators can now authorize** your aggregator for their communities

     

       164
       164
       +
       4. **Once authorized**, your aggregator can post to those communities

     

       165
       165
       +
       

     

       166
       166
       +
       ## Creating an Authorization

     

       167
       167
       +
       

     

       168
       168
       +
       Authorizations are created by community moderators, not by aggregators. The moderator writes a `social.coves.aggregator.authorization` record to their community's repository.

     

       169
       169
       +
       

     

       170
       170
       +
       See `docs/aggregators/SETUP_GUIDE.md` for more information on the authorization process.

     

       171
       171
       +
       

     

       172
       172
       +
       ## Posting to Communities

     

       173
       173
       +
       

     

       174
       174
       +
       Once authorized, your aggregator can post using:

     

       175
       175
       +
       

     

       176
       176
       +
       ```bash

     

       177
       177
       +
       curl -X POST https://api.coves.social/xrpc/social.coves.community.post.create \

     

       178
       178
       +
         -H "Authorization: Bearer $AGGREGATOR_ACCESS_JWT" \

     

       179
       179
       +
         -H "Content-Type: application/json" \

     

       180
       180
       +
         -d '{

     

       181
       181
       +
           "communityDid": "did:plc:...",

     

       182
       182
       +
           "post": {

     

       183
       183
       +
             "text": "Your post content",

     

       184
       184
       +
             "createdAt": "2024-01-15T12:00:00Z"

     

       185
       185
       +
           }

     

       186
       186
       +
         }'

     

       187
       187
       +
       ```

     

       188
       188
       +
       

     

       189
       189
       +
       ## Troubleshooting

     

       190
       190
       +
       

     

       191
       191
       +
       ### Error: "DomainVerificationFailed"

     

       192
       192
       +
       

     

       193
       193
       +
       - Verify `.well-known/atproto-did` is accessible: `curl https://yourdomain.com/.well-known/atproto-did`

     

       194
       194
       +
       - Check the content matches your DID exactly (no extra whitespace)

     

       195
       195
       +
       - Ensure HTTPS is working (not HTTP)

     

       196
       196
       +
       - Check CORS headers if accessing from browser

     

       197
       197
       +
       

     

       198
       198
       +
       ### Error: "AlreadyRegistered"

     

       199
       199
       +
       

     

       200
       200
       +
       - You've already registered this DID with this Coves instance

     

       201
       201
       +
       - This is safe to ignore if you're re-running the setup

     

       202
       202
       +
       

     

       203
       203
       +
       ### Error: "DIDResolutionFailed"

     

       204
       204
       +
       

     

       205
       205
       +
       - Your DID might be invalid or not found in the PLC directory

     

       206
       206
       +
       - Verify your DID exists: `curl https://plc.directory/<your-did>`

     

       207
       207
       +
       - Wait a few seconds and try again (PLC directory might be propagating)

     

       208
       208
       +
       

     

       209
       209
       +
       ### Service declaration not appearing

     

       210
       210
       +
       

     

       211
       211
       +
       - Wait 5-10 seconds for Jetstream consumer to index it

     

       212
       212
       +
       - Check the Jetstream logs for errors

     

       213
       213
       +
       - Verify the record was created: Check your PDS at `at://your-did/social.coves.aggregator.service/self`

     

       214
       214
       +
       

     

       215
       215
       +
       ## Example: Kagi News Aggregator

     

       216
       216
       +
       

     

       217
       217
       +
       For a complete reference implementation, see the Kagi News aggregator at `aggregators/kagi-news/`.

     

       218
       218
       +
       

     

       219
       219
       +
       The Kagi aggregator includes an automated setup script at [aggregators/kagi-news/scripts/setup.sh](../../aggregators/kagi-news/scripts/setup.sh) that demonstrates how to:

     

       220
       220
       +
       

     

       221
       221
       +
       - Automate the entire registration process

     

       222
       222
       +
       - Use environment variables for configuration

     

       223
       223
       +
       - Handle errors gracefully

     

       224
       224
       +
       - Integrate the setup into your aggregator project

     

       225
       225
       +
       

     

       226
       226
       +
       This shows how you can package scripts 1-4 into a single automated flow for your specific aggregator.

     

       227
       227
       +
       

     

       228
       228
       +
       ## Security Notes

     

       229
       229
       +
       

     

       230
       230
       +
       - **Never commit `aggregator-config.env`** to version control

     

       231
       231
       +
       - Store credentials securely (use environment variables or secret management)

     

       232
       232
       +
       - Rotate access tokens regularly

     

       233
       233
       +
       - Use HTTPS for all API calls

     

       234
       234
       +
       - Validate community authorization before posting

     

       235
       235
       +
       

     

       236
       236
       +
       ## More Information

     

       237
       237
       +
       

     

       238
       238
       +
       - [Aggregator Setup Guide](../../docs/aggregators/SETUP_GUIDE.md)

     

       239
       239
       +
       - [Aggregator PRD](../../docs/aggregators/PRD_AGGREGATORS.md)

     

       240
       240
       +
       - [atProto Identity Guide](../../ATPROTO_GUIDE.md)

     

       241
       241
       +
       - [Coves Communities PRD](../../docs/PRD_COMMUNITIES.md)

     

       242
       242
       +
       

     

       243
       243
       +
       ## Support

     

       244
       244
       +
       

     

       245
       245
       +
       If you encounter issues:

     

       246
       246
       +
       

     

       247
       247
       +
       1. Check the troubleshooting section above

     

       248
       248
       +
       2. Review the full documentation in `docs/aggregators/`

     

       249
       249
       +
       3. Open an issue on GitHub with:

     

       250
       250
       +
          - Which script failed

     

       251
       251
       +
          - Error message

     

       252
       252
       +
          - Your domain (without credentials)

+188 -1

aggregators/kagi-news/README.md

···

       31
       31
        
       │       ├── sample_rss_item.xml

     

       32
       32
        
       │       └── world.xml

     

       33
       33
        
       ├── scripts/

     

       34
       34
       -
       │   └── generate_did.py        # Helper to generate aggregator DID (TODO)

     

       34
       34
       +
       │   └── setup.sh               # Automated Coves registration script

     

       35
       35
       +
       ├── Dockerfile                 # Docker image definition

     

       36
       36
       +
       ├── docker-compose.yml         # Docker Compose configuration

     

       37
       37
       +
       ├── docker-entrypoint.sh       # Container entrypoint script

     

       38
       38
       +
       ├── .dockerignore              # Docker build exclusions

     

       35
       39
        
       ├── requirements.txt           # Python dependencies

     

       36
       40
        
       ├── config.example.yaml        # Example configuration

     

       37
       41
        
       ├── .env.example               # Environment variables template

     
···

       39
       43
        
       └── README.md

     

       40
       44
        
       ```

     

       41
       45
        
       

     

       46
       46
       +
       ## Registration with Coves

     

       47
       47
       +
       

     

       48
       48
       +
       Before running the aggregator, you must register it with a Coves instance. This creates a DID for your aggregator and registers it with Coves.

     

       49
       49
       +
       

     

       50
       50
       +
       ### Quick Setup (Automated)

     

       51
       51
       +
       

     

       52
       52
       +
       The automated setup script handles the entire registration process:

     

       53
       53
       +
       

     

       54
       54
       +
       ```bash

     

       55
       55
       +
       cd scripts

     

       56
       56
       +
       chmod +x setup.sh

     

       57
       57
       +
       ./setup.sh

     

       58
       58
       +
       ```

     

       59
       59
       +
       

     

       60
       60
       +
       This will:

     

       61
       61
       +
       1. **Create a PDS account** for your aggregator (generates a DID)

     

       62
       62
       +
       2. **Generate `.well-known/atproto-did`** file for domain verification

     

       63
       63
       +
       3. **Pause for manual upload** - you'll upload the file to your web server

     

       64
       64
       +
       4. **Register with Coves** instance via XRPC

     

       65
       65
       +
       5. **Create service declaration** record (indexed by Jetstream)

     

       66
       66
       +
       

     

       67
       67
       +
       **Manual step required:** During the process, you'll need to upload the `.well-known/atproto-did` file to your domain so it's accessible at `https://yourdomain.com/.well-known/atproto-did`.

     

       68
       68
       +
       

     

       69
       69
       +
       After completion, you'll have a `kagi-aggregator-config.env` file with:

     

       70
       70
       +
       - Aggregator DID and credentials

     

       71
       71
       +
       - Access/refresh JWTs

     

       72
       72
       +
       - Service declaration URI

     

       73
       73
       +
       

     

       74
       74
       +
       **Keep this file secure!** It contains your aggregator's credentials.

     

       75
       75
       +
       

     

       76
       76
       +
       ### Manual Setup (Step-by-step)

     

       77
       77
       +
       

     

       78
       78
       +
       Alternatively, use the generic setup scripts from the main Coves repo for more control:

     

       79
       79
       +
       

     

       80
       80
       +
       ```bash

     

       81
       81
       +
       # From the Coves project root

     

       82
       82
       +
       cd scripts/aggregator-setup

     

       83
       83
       +
       

     

       84
       84
       +
       # Follow the 4-step process

     

       85
       85
       +
       ./1-create-pds-account.sh

     

       86
       86
       +
       ./2-setup-wellknown.sh

     

       87
       87
       +
       ./3-register-with-coves.sh

     

       88
       88
       +
       ./4-create-service-declaration.sh

     

       89
       89
       +
       ```

     

       90
       90
       +
       

     

       91
       91
       +
       See [scripts/aggregator-setup/README.md](../../scripts/aggregator-setup/README.md) for detailed documentation on each step.

     

       92
       92
       +
       

     

       93
       93
       +
       ### What Happens During Registration?

     

       94
       94
       +
       

     

       95
       95
       +
       1. **PDS Account Creation**: Your aggregator gets a `did:plc:...` identifier

     

       96
       96
       +
       2. **Domain Verification**: Proves you control your aggregator's domain

     

       97
       97
       +
       3. **Coves Registration**: Inserts your DID into the Coves instance's `users` table

     

       98
       98
       +
       4. **Service Declaration**: Creates a record that gets indexed into the `aggregators` table

     

       99
       99
       +
       5. **Ready for Authorization**: Community moderators can now authorize your aggregator

     

       100
       100
       +
       

     

       101
       101
       +
       Once registered and authorized by a community, your aggregator can post content.

     

       102
       102
       +
       

     

       42
       103
        
       ## Setup

     

       43
       104
        
       

     

       44
       105
        
       ### Prerequisites

     

       45
       106
        
       

     

       46
       107
        
       - Python 3.11+

     

       47
       108
        
       - python3-venv package (`apt install python3.12-venv`)

     

       109
       109
       +
       - **Completed registration** (see above)

     

       48
       110
        
       

     

       49
       111
        
       ### Installation

     

       50
       112
        
       

     
···

       84
       146
        
       pytest --cov=src --cov-report=html

     

       85
       147
        
       ```

     

       86
       148
        
       

     

       149
       149
       +
       ## Deployment

     

       150
       150
       +
       

     

       151
       151
       +
       ### Docker Deployment (Recommended for Production)

     

       152
       152
       +
       

     

       153
       153
       +
       The easiest way to deploy the Kagi aggregator is using Docker. The cron job runs inside the container automatically.

     

       154
       154
       +
       

     

       155
       155
       +
       #### Prerequisites

     

       156
       156
       +
       

     

       157
       157
       +
       - Docker and Docker Compose installed

     

       158
       158
       +
       - Completed registration (you have `.env` with credentials)

     

       159
       159
       +
       - `config.yaml` configured with your feed mappings

     

       160
       160
       +
       

     

       161
       161
       +
       #### Quick Start

     

       162
       162
       +
       

     

       163
       163
       +
       1. **Configure your environment:**

     

       164
       164
       +
          ```bash

     

       165
       165
       +
          # Copy and edit configuration

     

       166
       166
       +
          cp config.example.yaml config.yaml

     

       167
       167
       +
          cp .env.example .env

     

       168
       168
       +
       

     

       169
       169
       +
          # Edit .env with your aggregator credentials

     

       170
       170
       +
          nano .env

     

       171
       171
       +
          ```

     

       172
       172
       +
       

     

       173
       173
       +
       2. **Start the aggregator:**

     

       174
       174
       +
          ```bash

     

       175
       175
       +
          docker compose up -d

     

       176
       176
       +
          ```

     

       177
       177
       +
       

     

       178
       178
       +
       3. **View logs:**

     

       179
       179
       +
          ```bash

     

       180
       180
       +
          docker compose logs -f

     

       181
       181
       +
          ```

     

       182
       182
       +
       

     

       183
       183
       +
       4. **Stop the aggregator:**

     

       184
       184
       +
          ```bash

     

       185
       185
       +
          docker compose down

     

       186
       186
       +
          ```

     

       187
       187
       +
       

     

       188
       188
       +
       #### Configuration

     

       189
       189
       +
       

     

       190
       190
       +
       The `docker-compose.yml` file supports these environment variables:

     

       191
       191
       +
       

     

       192
       192
       +
       - **`AGGREGATOR_HANDLE`** (required): Your aggregator's handle

     

       193
       193
       +
       - **`AGGREGATOR_PASSWORD`** (required): Your aggregator's password

     

       194
       194
       +
       - **`COVES_API_URL`** (optional): Override Coves API endpoint (defaults to `https://api.coves.social`)

     

       195
       195
       +
       - **`RUN_ON_STARTUP`** (optional): Set to `true` to run immediately on container start (useful for testing)

     

       196
       196
       +
       

     

       197
       197
       +
       #### Testing the Setup

     

       198
       198
       +
       

     

       199
       199
       +
       Run the aggregator immediately without waiting for cron:

     

       200
       200
       +
       

     

       201
       201
       +
       ```bash

     

       202
       202
       +
       # Run once and exit

     

       203
       203
       +
       docker compose run --rm kagi-aggregator python -m src.main

     

       204
       204
       +
       

     

       205
       205
       +
       # Or set RUN_ON_STARTUP=true in .env and restart

     

       206
       206
       +
       docker compose restart

     

       207
       207
       +
       ```

     

       208
       208
       +
       

     

       209
       209
       +
       #### Production Deployment

     

       210
       210
       +
       

     

       211
       211
       +
       For production, consider:

     

       212
       212
       +
       

     

       213
       213
       +
       1. **Using Docker Secrets** for credentials:

     

       214
       214
       +
          ```yaml

     

       215
       215
       +
          secrets:

     

       216
       216
       +
            aggregator_credentials:

     

       217
       217
       +
              file: ./secrets/aggregator.env

     

       218
       218
       +
          ```

     

       219
       219
       +
       

     

       220
       220
       +
       2. **Setting up log rotation** (already configured in docker-compose.yml):

     

       221
       221
       +
          - Max size: 10MB per file

     

       222
       222
       +
          - Max files: 3

     

       223
       223
       +
       

     

       224
       224
       +
       3. **Monitoring health checks:**

     

       225
       225
       +
          ```bash

     

       226
       226
       +
          docker inspect --format='{{.State.Health.Status}}' kagi-news-aggregator

     

       227
       227
       +
          ```

     

       228
       228
       +
       

     

       229
       229
       +
       4. **Auto-restart on failure** (already enabled with `restart: unless-stopped`)

     

       230
       230
       +
       

     

       231
       231
       +
       #### Viewing Cron Logs

     

       232
       232
       +
       

     

       233
       233
       +
       ```bash

     

       234
       234
       +
       # Follow cron execution logs

     

       235
       235
       +
       docker compose logs -f kagi-aggregator

     

       236
       236
       +
       

     

       237
       237
       +
       # View last 100 lines

     

       238
       238
       +
       docker compose logs --tail=100 kagi-aggregator

     

       239
       239
       +
       ```

     

       240
       240
       +
       

     

       241
       241
       +
       #### Updating the Aggregator

     

       242
       242
       +
       

     

       243
       243
       +
       ```bash

     

       244
       244
       +
       # Pull latest code

     

       245
       245
       +
       git pull

     

       246
       246
       +
       

     

       247
       247
       +
       # Rebuild and restart

     

       248
       248
       +
       docker compose up -d --build

     

       249
       249
       +
       ```

     

       250
       250
       +
       

     

       251
       251
       +
       ### Manual Deployment (Alternative)

     

       252
       252
       +
       

     

       253
       253
       +
       If you prefer running without Docker, use the traditional approach:

     

       254
       254
       +
       

     

       255
       255
       +
       1. **Install dependencies:**

     

       256
       256
       +
          ```bash

     

       257
       257
       +
          python3 -m venv venv

     

       258
       258
       +
          source venv/bin/activate

     

       259
       259
       +
          pip install -r requirements.txt

     

       260
       260
       +
          ```

     

       261
       261
       +
       

     

       262
       262
       +
       2. **Configure crontab:**

     

       263
       263
       +
          ```bash

     

       264
       264
       +
          # Edit the crontab file with your paths

     

       265
       265
       +
          # Then install it:

     

       266
       266
       +
          crontab crontab

     

       267
       267
       +
          ```

     

       268
       268
       +
       

     

       269
       269
       +
       3. **Verify cron is running:**

     

       270
       270
       +
          ```bash

     

       271
       271
       +
          crontab -l

     

       272
       272
       +
          ```

     

       273
       273
       +
       

     

       87
       274
        
       ## Development Status

     

       88
       275
        
       

     

       89
       276
        
       ### ✅ Phase 1-2 Complete (Oct 24, 2025)

+195

aggregators/kagi-news/scripts/setup.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       

     

       3
       3
       +
       # Script: setup-kagi-aggregator.sh

     

       4
       4
       +
       # Purpose: Complete setup script for Kagi News RSS aggregator

     

       5
       5
       +
       #

     

       6
       6
       +
       # This is a reference implementation showing automated setup for a specific aggregator.

     

       7
       7
       +
       # Other aggregator developers can use this as a template.

     

       8
       8
       +
       

     

       9
       9
       +
       set -e

     

       10
       10
       +
       

     

       11
       11
       +
       echo "================================================"

     

       12
       12
       +
       echo "Kagi News RSS Aggregator - Automated Setup"

     

       13
       13
       +
       echo "================================================"

     

       14
       14
       +
       echo ""

     

       15
       15
       +
       

     

       16
       16
       +
       # Configuration for Kagi aggregator

     

       17
       17
       +
       AGGREGATOR_NAME="kagi-news-bot"

     

       18
       18
       +
       DISPLAY_NAME="Kagi News RSS"

     

       19
       19
       +
       DESCRIPTION="Aggregates tech news from Kagi RSS feeds and posts to relevant communities"

     

       20
       20
       +
       SOURCE_URL="https://github.com/coves-social/kagi-aggregator"

     

       21
       21
       +
       

     

       22
       22
       +
       # Check if config already exists

     

       23
       23
       +
       if [ -f "kagi-aggregator-config.env" ]; then

     

       24
       24
       +
           echo "Configuration file already exists. Loading existing configuration..."

     

       25
       25
       +
           source kagi-aggregator-config.env

     

       26
       26
       +
           SKIP_ACCOUNT_CREATION=true

     

       27
       27
       +
       else

     

       28
       28
       +
           SKIP_ACCOUNT_CREATION=false

     

       29
       29
       +
       fi

     

       30
       30
       +
       

     

       31
       31
       +
       # Get runtime configuration

     

       32
       32
       +
       if [ "$SKIP_ACCOUNT_CREATION" = false ]; then

     

       33
       33
       +
           read -p "Enter PDS URL (default: https://bsky.social): " PDS_URL

     

       34
       34
       +
           PDS_URL=${PDS_URL:-https://bsky.social}

     

       35
       35
       +
       

     

       36
       36
       +
           read -p "Enter email for bot account: " EMAIL

     

       37
       37
       +
           read -sp "Enter password for bot account: " PASSWORD

     

       38
       38
       +
           echo ""

     

       39
       39
       +
       

     

       40
       40
       +
           # Generate handle

     

       41
       41
       +
           TIMESTAMP=$(date +%s)

     

       42
       42
       +
           HANDLE="$AGGREGATOR_NAME-$TIMESTAMP.bsky.social"

     

       43
       43
       +
       

     

       44
       44
       +
           echo ""

     

       45
       45
       +
           echo "Creating PDS account..."

     

       46
       46
       +
           echo "Handle: $HANDLE"

     

       47
       47
       +
       

     

       48
       48
       +
           # Create account

     

       49
       49
       +
           RESPONSE=$(curl -s -X POST "$PDS_URL/xrpc/com.atproto.server.createAccount" \

     

       50
       50
       +
               -H "Content-Type: application/json" \

     

       51
       51
       +
               -d "{

     

       52
       52
       +
                   \"handle\": \"$HANDLE\",

     

       53
       53
       +
                   \"email\": \"$EMAIL\",

     

       54
       54
       +
                   \"password\": \"$PASSWORD\"

     

       55
       55
       +
               }")

     

       56
       56
       +
       

     

       57
       57
       +
           if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       58
       58
       +
               echo "✗ Error creating account:"

     

       59
       59
       +
               echo "$RESPONSE" | jq '.'

     

       60
       60
       +
               exit 1

     

       61
       61
       +
           fi

     

       62
       62
       +
       

     

       63
       63
       +
           DID=$(echo "$RESPONSE" | jq -r '.did')

     

       64
       64
       +
           ACCESS_JWT=$(echo "$RESPONSE" | jq -r '.accessJwt')

     

       65
       65
       +
           REFRESH_JWT=$(echo "$RESPONSE" | jq -r '.refreshJwt')

     

       66
       66
       +
       

     

       67
       67
       +
           echo "✓ Account created: $DID"

     

       68
       68
       +
       

     

       69
       69
       +
           # Save configuration

     

       70
       70
       +
           cat > kagi-aggregator-config.env <<EOF

     

       71
       71
       +
       # Kagi Aggregator Configuration

     

       72
       72
       +
       AGGREGATOR_DID="$DID"

     

       73
       73
       +
       AGGREGATOR_HANDLE="$HANDLE"

     

       74
       74
       +
       AGGREGATOR_PDS_URL="$PDS_URL"

     

       75
       75
       +
       AGGREGATOR_EMAIL="$EMAIL"

     

       76
       76
       +
       AGGREGATOR_PASSWORD="$PASSWORD"

     

       77
       77
       +
       AGGREGATOR_ACCESS_JWT="$ACCESS_JWT"

     

       78
       78
       +
       AGGREGATOR_REFRESH_JWT="$REFRESH_JWT"

     

       79
       79
       +
       EOF

     

       80
       80
       +
       

     

       81
       81
       +
           echo "✓ Configuration saved to kagi-aggregator-config.env"

     

       82
       82
       +
       fi

     

       83
       83
       +
       

     

       84
       84
       +
       # Get domain and Coves instance

     

       85
       85
       +
       read -p "Enter aggregator domain (e.g., kagi-news.example.com): " DOMAIN

     

       86
       86
       +
       read -p "Enter Coves instance URL (default: https://api.coves.social): " COVES_URL

     

       87
       87
       +
       COVES_URL=${COVES_URL:-https://api.coves.social}

     

       88
       88
       +
       

     

       89
       89
       +
       # Setup .well-known

     

       90
       90
       +
       echo ""

     

       91
       91
       +
       echo "Setting up .well-known/atproto-did..."

     

       92
       92
       +
       mkdir -p .well-known

     

       93
       93
       +
       echo "$DID" > .well-known/atproto-did

     

       94
       94
       +
       echo "✓ Created .well-known/atproto-did"

     

       95
       95
       +
       

     

       96
       96
       +
       echo ""

     

       97
       97
       +
       echo "================================================"

     

       98
       98
       +
       echo "IMPORTANT: Manual Step Required"

     

       99
       99
       +
       echo "================================================"

     

       100
       100
       +
       echo ""

     

       101
       101
       +
       echo "Upload the .well-known directory to your web server at:"

     

       102
       102
       +
       echo "  https://$DOMAIN/.well-known/atproto-did"

     

       103
       103
       +
       echo ""

     

       104
       104
       +
       read -p "Press Enter when the file is uploaded and accessible..."

     

       105
       105
       +
       

     

       106
       106
       +
       # Verify .well-known

     

       107
       107
       +
       echo ""

     

       108
       108
       +
       echo "Verifying .well-known/atproto-did..."

     

       109
       109
       +
       WELLKNOWN_CONTENT=$(curl -s "https://$DOMAIN/.well-known/atproto-did" || echo "ERROR")

     

       110
       110
       +
       

     

       111
       111
       +
       if [ "$WELLKNOWN_CONTENT" != "$DID" ]; then

     

       112
       112
       +
           echo "✗ Error: .well-known/atproto-did not accessible or contains wrong DID"

     

       113
       113
       +
           echo "  Expected: $DID"

     

       114
       114
       +
           echo "  Got:      $WELLKNOWN_CONTENT"

     

       115
       115
       +
           exit 1

     

       116
       116
       +
       fi

     

       117
       117
       +
       

     

       118
       118
       +
       echo "✓ .well-known/atproto-did verified"

     

       119
       119
       +
       

     

       120
       120
       +
       # Register with Coves

     

       121
       121
       +
       echo ""

     

       122
       122
       +
       echo "Registering with Coves instance..."

     

       123
       123
       +
       RESPONSE=$(curl -s -X POST "$COVES_URL/xrpc/social.coves.aggregator.register" \

     

       124
       124
       +
           -H "Content-Type: application/json" \

     

       125
       125
       +
           -d "{

     

       126
       126
       +
               \"did\": \"$DID\",

     

       127
       127
       +
               \"domain\": \"$DOMAIN\"

     

       128
       128
       +
           }")

     

       129
       129
       +
       

     

       130
       130
       +
       if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       131
       131
       +
           echo "✗ Registration failed:"

     

       132
       132
       +
           echo "$RESPONSE" | jq '.'

     

       133
       133
       +
           exit 1

     

       134
       134
       +
       fi

     

       135
       135
       +
       

     

       136
       136
       +
       echo "✓ Registered with Coves"

     

       137
       137
       +
       

     

       138
       138
       +
       # Create service declaration

     

       139
       139
       +
       echo ""

     

       140
       140
       +
       echo "Creating service declaration..."

     

       141
       141
       +
       SERVICE_RECORD=$(cat <<EOF

     

       142
       142
       +
       {

     

       143
       143
       +
           "\$type": "social.coves.aggregator.service",

     

       144
       144
       +
           "did": "$DID",

     

       145
       145
       +
           "displayName": "$DISPLAY_NAME",

     

       146
       146
       +
           "description": "$DESCRIPTION",

     

       147
       147
       +
           "sourceUrl": "$SOURCE_URL",

     

       148
       148
       +
           "createdAt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"

     

       149
       149
       +
       }

     

       150
       150
       +
       EOF

     

       151
       151
       +
       )

     

       152
       152
       +
       

     

       153
       153
       +
       RESPONSE=$(curl -s -X POST "$PDS_URL/xrpc/com.atproto.repo.createRecord" \

     

       154
       154
       +
           -H "Authorization: Bearer $ACCESS_JWT" \

     

       155
       155
       +
           -H "Content-Type: application/json" \

     

       156
       156
       +
           -d "{

     

       157
       157
       +
               \"repo\": \"$DID\",

     

       158
       158
       +
               \"collection\": \"social.coves.aggregator.service\",

     

       159
       159
       +
               \"rkey\": \"self\",

     

       160
       160
       +
               \"record\": $SERVICE_RECORD

     

       161
       161
       +
           }")

     

       162
       162
       +
       

     

       163
       163
       +
       if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then

     

       164
       164
       +
           echo "✗ Failed to create service declaration:"

     

       165
       165
       +
           echo "$RESPONSE" | jq '.'

     

       166
       166
       +
           exit 1

     

       167
       167
       +
       fi

     

       168
       168
       +
       

     

       169
       169
       +
       RECORD_URI=$(echo "$RESPONSE" | jq -r '.uri')

     

       170
       170
       +
       echo "✓ Service declaration created: $RECORD_URI"

     

       171
       171
       +
       

     

       172
       172
       +
       # Save final configuration

     

       173
       173
       +
       cat >> kagi-aggregator-config.env <<EOF

     

       174
       174
       +
       

     

       175
       175
       +
       # Setup completed on $(date)

     

       176
       176
       +
       AGGREGATOR_DOMAIN="$DOMAIN"

     

       177
       177
       +
       COVES_INSTANCE_URL="$COVES_URL"

     

       178
       178
       +
       SERVICE_DECLARATION_URI="$RECORD_URI"

     

       179
       179
       +
       EOF

     

       180
       180
       +
       

     

       181
       181
       +
       echo ""

     

       182
       182
       +
       echo "================================================"

     

       183
       183
       +
       echo "✓ Kagi Aggregator Setup Complete!"

     

       184
       184
       +
       echo "================================================"

     

       185
       185
       +
       echo ""

     

       186
       186
       +
       echo "Configuration saved to: kagi-aggregator-config.env"

     

       187
       187
       +
       echo ""

     

       188
       188
       +
       echo "Your aggregator is now registered and ready to use."

     

       189
       189
       +
       echo ""

     

       190
       190
       +
       echo "Next steps:"

     

       191
       191
       +
       echo "1. Start your aggregator bot: npm start (or appropriate command)"

     

       192
       192
       +
       echo "2. Community moderators can authorize your aggregator"

     

       193
       193
       +
       echo "3. Once authorized, your bot can start posting"

     

       194
       194
       +
       echo ""

     

       195
       195
       +
       echo "See docs/aggregators/SETUP_GUIDE.md for more information"

+55

aggregators/kagi-news/.dockerignore

···

       1
       1
       +
       # Git

     

       2
       2
       +
       .git

     

       3
       3
       +
       .gitignore

     

       4
       4
       +
       

     

       5
       5
       +
       # Python

     

       6
       6
       +
       __pycache__

     

       7
       7
       +
       *.py[cod]

     

       8
       8
       +
       *$py.class

     

       9
       9
       +
       *.so

     

       10
       10
       +
       .Python

     

       11
       11
       +
       venv/

     

       12
       12
       +
       *.egg-info

     

       13
       13
       +
       dist/

     

       14
       14
       +
       build/

     

       15
       15
       +
       

     

       16
       16
       +
       # Testing

     

       17
       17
       +
       .pytest_cache/

     

       18
       18
       +
       .coverage

     

       19
       19
       +
       htmlcov/

     

       20
       20
       +
       .tox/

     

       21
       21
       +
       .hypothesis/

     

       22
       22
       +
       

     

       23
       23
       +
       # IDE

     

       24
       24
       +
       .vscode/

     

       25
       25
       +
       .idea/

     

       26
       26
       +
       *.swp

     

       27
       27
       +
       *.swo

     

       28
       28
       +
       *~

     

       29
       29
       +
       

     

       30
       30
       +
       # Environment

     

       31
       31
       +
       .env.local

     

       32
       32
       +
       .env.*.local

     

       33
       33
       +
       

     

       34
       34
       +
       # Data and logs

     

       35
       35
       +
       data/

     

       36
       36
       +
       *.log

     

       37
       37
       +
       

     

       38
       38
       +
       # Documentation

     

       39
       39
       +
       README.md

     

       40
       40
       +
       docs/

     

       41
       41
       +
       

     

       42
       42
       +
       # Docker

     

       43
       43
       +
       Dockerfile

     

       44
       44
       +
       docker-compose.yml

     

       45
       45
       +
       .dockerignore

     

       46
       46
       +
       

     

       47
       47
       +
       # Development

     

       48
       48
       +
       tests/

     

       49
       49
       +
       pytest.ini

     

       50
       50
       +
       mypy.ini

     

       51
       51
       +
       .mypy_cache/

     

       52
       52
       +
       

     

       53
       53
       +
       # OS

     

       54
       54
       +
       .DS_Store

     

       55
       55
       +
       Thumbs.db

+53

aggregators/kagi-news/Dockerfile

···

       1
       1
       +
       # Kagi News RSS Aggregator

     

       2
       2
       +
       # Production-ready Docker image with cron scheduler

     

       3
       3
       +
       

     

       4
       4
       +
       FROM python:3.11-slim

     

       5
       5
       +
       

     

       6
       6
       +
       # Install cron and other utilities

     

       7
       7
       +
       RUN apt-get update && apt-get install -y \

     

       8
       8
       +
           cron \

     

       9
       9
       +
           curl \

     

       10
       10
       +
           procps \

     

       11
       11
       +
           && rm -rf /var/lib/apt/lists/*

     

       12
       12
       +
       

     

       13
       13
       +
       # Set working directory

     

       14
       14
       +
       WORKDIR /app

     

       15
       15
       +
       

     

       16
       16
       +
       # Copy requirements first for better caching

     

       17
       17
       +
       COPY requirements.txt .

     

       18
       18
       +
       

     

       19
       19
       +
       # Install Python dependencies (exclude dev/test deps in production)

     

       20
       20
       +
       RUN pip install --no-cache-dir \

     

       21
       21
       +
           feedparser==6.0.11 \

     

       22
       22
       +
           beautifulsoup4==4.12.3 \

     

       23
       23
       +
           requests==2.31.0 \

     

       24
       24
       +
           atproto==0.0.55 \

     

       25
       25
       +
           pyyaml==6.0.1

     

       26
       26
       +
       

     

       27
       27
       +
       # Copy application code

     

       28
       28
       +
       COPY src/ ./src/

     

       29
       29
       +
       COPY config.yaml ./

     

       30
       30
       +
       

     

       31
       31
       +
       # Copy crontab file

     

       32
       32
       +
       COPY crontab /etc/cron.d/kagi-aggregator

     

       33
       33
       +
       

     

       34
       34
       +
       # Give execution rights on the cron job and apply it

     

       35
       35
       +
       RUN chmod 0644 /etc/cron.d/kagi-aggregator && \

     

       36
       36
       +
           crontab /etc/cron.d/kagi-aggregator

     

       37
       37
       +
       

     

       38
       38
       +
       # Create log file to be able to run tail

     

       39
       39
       +
       RUN touch /var/log/cron.log

     

       40
       40
       +
       

     

       41
       41
       +
       # Copy entrypoint script

     

       42
       42
       +
       COPY docker-entrypoint.sh /usr/local/bin/

     

       43
       43
       +
       RUN chmod +x /usr/local/bin/docker-entrypoint.sh

     

       44
       44
       +
       

     

       45
       45
       +
       # Health check - verify cron is running

     

       46
       46
       +
       HEALTHCHECK --interval=60s --timeout=10s --start-period=10s --retries=3 \

     

       47
       47
       +
           CMD pgrep cron || exit 1

     

       48
       48
       +
       

     

       49
       49
       +
       # Run the entrypoint script

     

       50
       50
       +
       ENTRYPOINT ["docker-entrypoint.sh"]

     

       51
       51
       +
       

     

       52
       52
       +
       # Default command: tail the cron log

     

       53
       53
       +
       CMD ["tail", "-f", "/var/log/cron.log"]

+48

aggregators/kagi-news/docker-compose.yml

···

       1
       1
       +
       services:

     

       2
       2
       +
         kagi-aggregator:

     

       3
       3
       +
           build:

     

       4
       4
       +
             context: .

     

       5
       5
       +
             dockerfile: Dockerfile

     

       6
       6
       +
           container_name: kagi-news-aggregator

     

       7
       7
       +
           restart: unless-stopped

     

       8
       8
       +
       

     

       9
       9
       +
           # Environment variables - override in .env file or here

     

       10
       10
       +
           environment:

     

       11
       11
       +
             # Required: Aggregator credentials

     

       12
       12
       +
             - AGGREGATOR_HANDLE=${AGGREGATOR_HANDLE}

     

       13
       13
       +
             - AGGREGATOR_PASSWORD=${AGGREGATOR_PASSWORD}

     

       14
       14
       +
       

     

       15
       15
       +
             # Optional: Override Coves API URL

     

       16
       16
       +
             - COVES_API_URL=${COVES_API_URL:-https://api.coves.social}

     

       17
       17
       +
       

     

       18
       18
       +
             # Optional: Run immediately on startup (useful for testing)

     

       19
       19
       +
             - RUN_ON_STARTUP=${RUN_ON_STARTUP:-false}

     

       20
       20
       +
       

     

       21
       21
       +
           # Mount config file if you want to modify it without rebuilding

     

       22
       22
       +
           volumes:

     

       23
       23
       +
             - ./config.yaml:/app/config.yaml:ro

     

       24
       24
       +
             - ./data:/app/data  # For state persistence (if implemented)

     

       25
       25
       +
       

     

       26
       26
       +
           # Use env_file to load credentials from .env

     

       27
       27
       +
           env_file:

     

       28
       28
       +
             - .env

     

       29
       29
       +
       

     

       30
       30
       +
           # Logging configuration

     

       31
       31
       +
           logging:

     

       32
       32
       +
             driver: "json-file"

     

       33
       33
       +
             options:

     

       34
       34
       +
               max-size: "10m"

     

       35
       35
       +
               max-file: "3"

     

       36
       36
       +
       

     

       37
       37
       +
           # Health check

     

       38
       38
       +
           healthcheck:

     

       39
       39
       +
             test: ["CMD", "pgrep", "cron"]

     

       40
       40
       +
             interval: 60s

     

       41
       41
       +
             timeout: 10s

     

       42
       42
       +
             retries: 3

     

       43
       43
       +
             start_period: 10s

     

       44
       44
       +
       

     

       45
       45
       +
       # Optional: Networks for multi-container setups

     

       46
       46
       +
       # networks:

     

       47
       47
       +
       #   coves:

     

       48
       48
       +
       #     external: true

+41

aggregators/kagi-news/docker-entrypoint.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       set -e

     

       3
       3
       +
       

     

       4
       4
       +
       echo "Starting Kagi News RSS Aggregator..."

     

       5
       5
       +
       echo "========================================="

     

       6
       6
       +
       

     

       7
       7
       +
       # Load environment variables if .env file exists

     

       8
       8
       +
       if [ -f /app/.env ]; then

     

       9
       9
       +
           echo "Loading environment variables from .env"

     

       10
       10
       +
           export $(grep -v '^#' /app/.env | xargs)

     

       11
       11
       +
       fi

     

       12
       12
       +
       

     

       13
       13
       +
       # Validate required environment variables

     

       14
       14
       +
       if [ -z "$AGGREGATOR_HANDLE" ] || [ -z "$AGGREGATOR_PASSWORD" ]; then

     

       15
       15
       +
           echo "ERROR: Missing required environment variables!"

     

       16
       16
       +
           echo "Please set AGGREGATOR_HANDLE and AGGREGATOR_PASSWORD"

     

       17
       17
       +
           exit 1

     

       18
       18
       +
       fi

     

       19
       19
       +
       

     

       20
       20
       +
       echo "Aggregator Handle: $AGGREGATOR_HANDLE"

     

       21
       21
       +
       echo "Cron schedule loaded from /etc/cron.d/kagi-aggregator"

     

       22
       22
       +
       

     

       23
       23
       +
       # Start cron in the background

     

       24
       24
       +
       echo "Starting cron daemon..."

     

       25
       25
       +
       cron

     

       26
       26
       +
       

     

       27
       27
       +
       # Optional: Run aggregator immediately on startup (for testing)

     

       28
       28
       +
       if [ "$RUN_ON_STARTUP" = "true" ]; then

     

       29
       29
       +
           echo "Running aggregator immediately (RUN_ON_STARTUP=true)..."

     

       30
       30
       +
           cd /app && python -m src.main

     

       31
       31
       +
       fi

     

       32
       32
       +
       

     

       33
       33
       +
       echo "========================================="

     

       34
       34
       +
       echo "Kagi News Aggregator is running!"

     

       35
       35
       +
       echo "Cron schedule: Daily at 1 PM UTC"

     

       36
       36
       +
       echo "Logs will appear below:"

     

       37
       37
       +
       echo "========================================="

     

       38
       38
       +
       echo ""

     

       39
       39
       +
       

     

       40
       40
       +
       # Execute the command passed to docker run (defaults to tail -f /var/log/cron.log)

     

       41
       41
       +
       exec "$@"

+20

.beads/.gitignore

···

       1
       1
       +
       # SQLite databases

     

       2
       2
       +
       *.db

     

       3
       3
       +
       *.db-journal

     

       4
       4
       +
       *.db-wal

     

       5
       5
       +
       *.db-shm

     

       6
       6
       +
       

     

       7
       7
       +
       # Daemon runtime files

     

       8
       8
       +
       daemon.lock

     

       9
       9
       +
       daemon.log

     

       10
       10
       +
       daemon.pid

     

       11
       11
       +
       bd.sock

     

       12
       12
       +
       

     

       13
       13
       +
       # Legacy database files

     

       14
       14
       +
       db.sqlite

     

       15
       15
       +
       bd.db

     

       16
       16
       +
       

     

       17
       17
       +
       # Keep JSONL exports and config (source of truth for git)

     

       18
       18
       +
       !*.jsonl

     

       19
       19
       +
       !metadata.json

     

       20
       20
       +
       !config.json

+56

.beads/config.yaml

···

       1
       1
       +
       # Beads Configuration File

     

       2
       2
       +
       # This file configures default behavior for all bd commands in this repository

     

       3
       3
       +
       # All settings can also be set via environment variables (BD_* prefix)

     

       4
       4
       +
       # or overridden with command-line flags

     

       5
       5
       +
       

     

       6
       6
       +
       # Issue prefix for this repository (used by bd init)

     

       7
       7
       +
       # If not set, bd init will auto-detect from directory name

     

       8
       8
       +
       # Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.

     

       9
       9
       +
       # issue-prefix: ""

     

       10
       10
       +
       

     

       11
       11
       +
       # Use no-db mode: load from JSONL, no SQLite, write back after each command

     

       12
       12
       +
       # When true, bd will use .beads/issues.jsonl as the source of truth

     

       13
       13
       +
       # instead of SQLite database

     

       14
       14
       +
       # no-db: false

     

       15
       15
       +
       

     

       16
       16
       +
       # Disable daemon for RPC communication (forces direct database access)

     

       17
       17
       +
       # no-daemon: false

     

       18
       18
       +
       

     

       19
       19
       +
       # Disable auto-flush of database to JSONL after mutations

     

       20
       20
       +
       # no-auto-flush: false

     

       21
       21
       +
       

     

       22
       22
       +
       # Disable auto-import from JSONL when it's newer than database

     

       23
       23
       +
       # no-auto-import: false

     

       24
       24
       +
       

     

       25
       25
       +
       # Enable JSON output by default

     

       26
       26
       +
       # json: false

     

       27
       27
       +
       

     

       28
       28
       +
       # Default actor for audit trails (overridden by BD_ACTOR or --actor)

     

       29
       29
       +
       # actor: ""

     

       30
       30
       +
       

     

       31
       31
       +
       # Path to database (overridden by BEADS_DB or --db)

     

       32
       32
       +
       # db: ""

     

       33
       33
       +
       

     

       34
       34
       +
       # Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)

     

       35
       35
       +
       # auto-start-daemon: true

     

       36
       36
       +
       

     

       37
       37
       +
       # Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)

     

       38
       38
       +
       # flush-debounce: "5s"

     

       39
       39
       +
       

     

       40
       40
       +
       # Multi-repo configuration (experimental - bd-307)

     

       41
       41
       +
       # Allows hydrating from multiple repositories and routing writes to the correct JSONL

     

       42
       42
       +
       # repos:

     

       43
       43
       +
       #   primary: "."  # Primary repo (where this database lives)

     

       44
       44
       +
       #   additional:   # Additional repos to hydrate from (read-only)

     

       45
       45
       +
       #     - ~/beads-planning  # Personal planning repo

     

       46
       46
       +
       #     - ~/work-planning   # Work planning repo

     

       47
       47
       +
       

     

       48
       48
       +
       # Integration settings (access with 'bd config get/set')

     

       49
       49
       +
       # These are stored in the database, not in this file:

     

       50
       50
       +
       # - jira.url

     

       51
       51
       +
       # - jira.project

     

       52
       52
       +
       # - linear.url

     

       53
       53
       +
       # - linear.api-key

     

       54
       54
       +
       # - github.org

     

       55
       55
       +
       # - github.repo

     

       56
       56
       +
       # - sync.branch - Git branch for beads commits (use BEADS_SYNC_BRANCH env var or bd config set)

.beads/metadata.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "database": "beads.db",

     

       3
       3
       +
         "jsonl_export": "beads.jsonl"

     

       4
       4
       +
       }

.gitattributes

···

       1
       1
       +
       

     

       2
       2
       +
       # Use bd merge for beads JSONL files

     

       3
       3
       +
       .beads/beads.jsonl merge=beads

+131

AGENTS.md

···

       1
       1
       +
       # AI Agent Guidelines for Coves

     

       2
       2
       +
       

     

       3
       3
       +
       ## Issue Tracking with bd (beads)

     

       4
       4
       +
       

     

       5
       5
       +
       **IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

     

       6
       6
       +
       

     

       7
       7
       +
       ### Why bd?

     

       8
       8
       +
       

     

       9
       9
       +
       - Dependency-aware: Track blockers and relationships between issues

     

       10
       10
       +
       - Git-friendly: Auto-syncs to JSONL for version control

     

       11
       11
       +
       - Agent-optimized: JSON output, ready work detection, discovered-from links

     

       12
       12
       +
       - Prevents duplicate tracking systems and confusion

     

       13
       13
       +
       

     

       14
       14
       +
       ### Quick Start

     

       15
       15
       +
       

     

       16
       16
       +
       **Check for ready work:**

     

       17
       17
       +
       ```bash

     

       18
       18
       +
       bd ready --json

     

       19
       19
       +
       ```

     

       20
       20
       +
       

     

       21
       21
       +
       **Create new issues:**

     

       22
       22
       +
       ```bash

     

       23
       23
       +
       bd create "Issue title" -t bug|feature|task -p 0-4 --json

     

       24
       24
       +
       bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json

     

       25
       25
       +
       ```

     

       26
       26
       +
       

     

       27
       27
       +
       **Claim and update:**

     

       28
       28
       +
       ```bash

     

       29
       29
       +
       bd update bd-42 --status in_progress --json

     

       30
       30
       +
       bd update bd-42 --priority 1 --json

     

       31
       31
       +
       ```

     

       32
       32
       +
       

     

       33
       33
       +
       **Complete work:**

     

       34
       34
       +
       ```bash

     

       35
       35
       +
       bd close bd-42 --reason "Completed" --json

     

       36
       36
       +
       ```

     

       37
       37
       +
       

     

       38
       38
       +
       ### Issue Types

     

       39
       39
       +
       

     

       40
       40
       +
       - `bug` - Something broken

     

       41
       41
       +
       - `feature` - New functionality

     

       42
       42
       +
       - `task` - Work item (tests, docs, refactoring)

     

       43
       43
       +
       - `epic` - Large feature with subtasks

     

       44
       44
       +
       - `chore` - Maintenance (dependencies, tooling)

     

       45
       45
       +
       

     

       46
       46
       +
       ### Priorities

     

       47
       47
       +
       

     

       48
       48
       +
       - `0` - Critical (security, data loss, broken builds)

     

       49
       49
       +
       - `1` - High (major features, important bugs)

     

       50
       50
       +
       - `2` - Medium (default, nice-to-have)

     

       51
       51
       +
       - `3` - Low (polish, optimization)

     

       52
       52
       +
       - `4` - Backlog (future ideas)

     

       53
       53
       +
       

     

       54
       54
       +
       ### Workflow for AI Agents

     

       55
       55
       +
       

     

       56
       56
       +
       1. **Check ready work**: `bd ready` shows unblocked issues

     

       57
       57
       +
       2. **Claim your task**: `bd update <id> --status in_progress`

     

       58
       58
       +
       3. **Work on it**: Implement, test, document

     

       59
       59
       +
       4. **Discover new work?** Create linked issue:

     

       60
       60
       +
          - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`

     

       61
       61
       +
       5. **Complete**: `bd close <id> --reason "Done"`

     

       62
       62
       +
       6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state

     

       63
       63
       +
       

     

       64
       64
       +
       ### Auto-Sync

     

       65
       65
       +
       

     

       66
       66
       +
       bd automatically syncs with git:

     

       67
       67
       +
       - Exports to `.beads/issues.jsonl` after changes (5s debounce)

     

       68
       68
       +
       - Imports from JSONL when newer (e.g., after `git pull`)

     

       69
       69
       +
       - No manual export/import needed!

     

       70
       70
       +
       

     

       71
       71
       +
       ### MCP Server (Recommended)

     

       72
       72
       +
       

     

       73
       73
       +
       If using Claude or MCP-compatible clients, install the beads MCP server:

     

       74
       74
       +
       

     

       75
       75
       +
       ```bash

     

       76
       76
       +
       pip install beads-mcp

     

       77
       77
       +
       ```

     

       78
       78
       +
       

     

       79
       79
       +
       Add to MCP config (e.g., `~/.config/claude/config.json`):

     

       80
       80
       +
       ```json

     

       81
       81
       +
       {

     

       82
       82
       +
         "beads": {

     

       83
       83
       +
           "command": "beads-mcp",

     

       84
       84
       +
           "args": []

     

       85
       85
       +
         }

     

       86
       86
       +
       }

     

       87
       87
       +
       ```

     

       88
       88
       +
       

     

       89
       89
       +
       Then use `mcp__beads__*` functions instead of CLI commands.

     

       90
       90
       +
       

     

       91
       91
       +
       ### Managing AI-Generated Planning Documents

     

       92
       92
       +
       

     

       93
       93
       +
       AI assistants often create planning and design documents during development:

     

       94
       94
       +
       - PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md

     

       95
       95
       +
       - DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md

     

       96
       96
       +
       - TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

     

       97
       97
       +
       

     

       98
       98
       +
       **Best Practice: Use a dedicated directory for these ephemeral files**

     

       99
       99
       +
       

     

       100
       100
       +
       **Recommended approach:**

     

       101
       101
       +
       - Create a `history/` directory in the project root

     

       102
       102
       +
       - Store ALL AI-generated planning/design docs in `history/`

     

       103
       103
       +
       - Keep the repository root clean and focused on permanent project files

     

       104
       104
       +
       - Only access `history/` when explicitly asked to review past planning

     

       105
       105
       +
       

     

       106
       106
       +
       **Example .gitignore entry (optional):**

     

       107
       107
       +
       ```

     

       108
       108
       +
       # AI planning documents (ephemeral)

     

       109
       109
       +
       history/

     

       110
       110
       +
       ```

     

       111
       111
       +
       

     

       112
       112
       +
       **Benefits:**

     

       113
       113
       +
       - ✅ Clean repository root

     

       114
       114
       +
       - ✅ Clear separation between ephemeral and permanent documentation

     

       115
       115
       +
       - ✅ Easy to exclude from version control if desired

     

       116
       116
       +
       - ✅ Preserves planning history for archeological research

     

       117
       117
       +
       - ✅ Reduces noise when browsing the project

     

       118
       118
       +
       

     

       119
       119
       +
       ### Important Rules

     

       120
       120
       +
       

     

       121
       121
       +
       - ✅ Use bd for ALL task tracking

     

       122
       122
       +
       - ✅ Always use `--json` flag for programmatic use

     

       123
       123
       +
       - ✅ Link discovered work with `discovered-from` dependencies

     

       124
       124
       +
       - ✅ Check `bd ready` before asking "what should I work on?"

     

       125
       125
       +
       - ✅ Store AI planning docs in `history/` directory

     

       126
       126
       +
       - ❌ Do NOT create markdown TODO lists

     

       127
       127
       +
       - ❌ Do NOT use external issue trackers

     

       128
       128
       +
       - ❌ Do NOT duplicate tracking systems

     

       129
       129
       +
       - ❌ Do NOT clutter repo root with planning documents

     

       130
       130
       +
       

     

       131
       131
       +
       For more details, see the [beads repository](https://github.com/steveyegge/beads).

+8 -8

internal/core/communities/community.go

···

       123
       123
        
       

     

       124
       124
        
       // ListCommunitiesRequest represents query parameters for listing communities

     

       125
       125
        
       type ListCommunitiesRequest struct {

     

       126
       126
       -
       	Visibility string `json:"visibility,omitempty"`

     

       127
       127
       -
       	HostedBy   string `json:"hostedBy,omitempty"`

     

       128
       128
       -
       	SortBy     string `json:"sortBy,omitempty"`

     

       129
       129
       -
       	SortOrder  string `json:"sortOrder,omitempty"`

     

       130
       130
       -
       	Limit      int    `json:"limit"`

     

       131
       131
       -
       	Offset     int    `json:"offset"`

     

       126
       126
       +
       	Sort       string `json:"sort,omitempty"`       // Enum: popular, active, new, alphabetical

     

       127
       127
       +
       	Visibility string `json:"visibility,omitempty"` // Filter: public, unlisted, private

     

       128
       128
       +
       	Category   string `json:"category,omitempty"`   // Optional: filter by category (future)

     

       129
       129
       +
       	Language   string `json:"language,omitempty"`   // Optional: filter by language (future)

     

       130
       130
       +
       	Limit      int    `json:"limit"`                // 1-100, default 50

     

       131
       131
       +
       	Offset     int    `json:"offset"`               // Pagination offset

     

       132
       132
        
       }

     

       133
       133
        
       

     

       134
       134
        
       // SearchCommunitiesRequest represents query parameters for searching communities

     
···

       159
       159
        
       	name := c.Handle[:communityIndex]

     

       160
       160
        
       

     

       161
       161
        
       	// Extract instance domain (everything after ".community.")

     

       162
       162
       -
       	// len(".community.") = 11

     

       163
       163
       -
       	instanceDomain := c.Handle[communityIndex+11:]

     

       162
       162
       +
       	communitySegment := ".community."

     

       163
       163
       +
       	instanceDomain := c.Handle[communityIndex+len(communitySegment):]

     

       164
       164
        
       

     

       165
       165
        
       	return fmt.Sprintf("!%s@%s", name, instanceDomain)

     

       166
       166
        
       }

+2 -2

internal/core/communities/interfaces.go

···

       16
       16
        
       	UpdateCredentials(ctx context.Context, did, accessToken, refreshToken string) error

     

       17
       17
        
       

     

       18
       18
        
       	// Listing & Search

     

       19
       19
       -
       	List(ctx context.Context, req ListCommunitiesRequest) ([]*Community, int, error) // Returns communities + total count

     

       19
       19
       +
       	List(ctx context.Context, req ListCommunitiesRequest) ([]*Community, error)

     

       20
       20
        
       	Search(ctx context.Context, req SearchCommunitiesRequest) ([]*Community, int, error)

     

       21
       21
        
       

     

       22
       22
        
       	// Subscriptions (lightweight feed follows)

     
···

       62
       62
        
       	CreateCommunity(ctx context.Context, req CreateCommunityRequest) (*Community, error)

     

       63
       63
        
       	GetCommunity(ctx context.Context, identifier string) (*Community, error) // identifier can be DID or handle

     

       64
       64
        
       	UpdateCommunity(ctx context.Context, req UpdateCommunityRequest) (*Community, error)

     

       65
       65
       -
       	ListCommunities(ctx context.Context, req ListCommunitiesRequest) ([]*Community, int, error)

     

       65
       65
       +
       	ListCommunities(ctx context.Context, req ListCommunitiesRequest) ([]*Community, error)

     

       66
       66
        
       	SearchCommunities(ctx context.Context, req SearchCommunitiesRequest) ([]*Community, int, error)

     

       67
       67
        
       

     

       68
       68
        
       	// Subscription operations (write-forward: creates record in user's PDS)

+57

scripts/backup.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       # Coves Database Backup Script

     

       3
       3
       +
       # Usage: ./scripts/backup.sh

     

       4
       4
       +
       #

     

       5
       5
       +
       # Creates timestamped PostgreSQL backups in ./backups/

     

       6
       6
       +
       # Retention: Keeps last 30 days of backups

     

       7
       7
       +
       

     

       8
       8
       +
       set -e

     

       9
       9
       +
       

     

       10
       10
       +
       SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

     

       11
       11
       +
       PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

     

       12
       12
       +
       BACKUP_DIR="$PROJECT_DIR/backups"

     

       13
       13
       +
       COMPOSE_FILE="$PROJECT_DIR/docker-compose.prod.yml"

     

       14
       14
       +
       

     

       15
       15
       +
       # Load environment

     

       16
       16
       +
       set -a

     

       17
       17
       +
       source "$PROJECT_DIR/.env.prod"

     

       18
       18
       +
       set +a

     

       19
       19
       +
       

     

       20
       20
       +
       # Colors

     

       21
       21
       +
       GREEN='\033[0;32m'

     

       22
       22
       +
       YELLOW='\033[1;33m'

     

       23
       23
       +
       NC='\033[0m'

     

       24
       24
       +
       

     

       25
       25
       +
       log() { echo -e "${GREEN}[BACKUP]${NC} $1"; }

     

       26
       26
       +
       warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }

     

       27
       27
       +
       

     

       28
       28
       +
       # Create backup directory

     

       29
       29
       +
       mkdir -p "$BACKUP_DIR"

     

       30
       30
       +
       

     

       31
       31
       +
       # Generate timestamp

     

       32
       32
       +
       TIMESTAMP=$(date +%Y%m%d_%H%M%S)

     

       33
       33
       +
       BACKUP_FILE="$BACKUP_DIR/coves_${TIMESTAMP}.sql.gz"

     

       34
       34
       +
       

     

       35
       35
       +
       log "Starting backup..."

     

       36
       36
       +
       

     

       37
       37
       +
       # Run pg_dump inside container

     

       38
       38
       +
       docker compose -f "$COMPOSE_FILE" exec -T postgres \

     

       39
       39
       +
           pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists \

     

       40
       40
       +
           | gzip > "$BACKUP_FILE"

     

       41
       41
       +
       

     

       42
       42
       +
       # Get file size

     

       43
       43
       +
       SIZE=$(du -h "$BACKUP_FILE" | cut -f1)

     

       44
       44
       +
       

     

       45
       45
       +
       log "✅ Backup complete: $BACKUP_FILE ($SIZE)"

     

       46
       46
       +
       

     

       47
       47
       +
       # Cleanup old backups (keep last 30 days)

     

       48
       48
       +
       log "Cleaning up backups older than 30 days..."

     

       49
       49
       +
       find "$BACKUP_DIR" -name "coves_*.sql.gz" -mtime +30 -delete

     

       50
       50
       +
       

     

       51
       51
       +
       # List recent backups

     

       52
       52
       +
       log ""

     

       53
       53
       +
       log "Recent backups:"

     

       54
       54
       +
       ls -lh "$BACKUP_DIR"/*.sql.gz 2>/dev/null | tail -5

     

       55
       55
       +
       

     

       56
       56
       +
       log ""

     

       57
       57
       +
       log "To restore: gunzip -c $BACKUP_FILE | docker compose -f docker-compose.prod.yml exec -T postgres psql -U $POSTGRES_USER -d $POSTGRES_DB"

+133

scripts/deploy.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       # Coves Deployment Script

     

       3
       3
       +
       # Usage: ./scripts/deploy.sh [service]

     

       4
       4
       +
       #

     

       5
       5
       +
       # Examples:

     

       6
       6
       +
       #   ./scripts/deploy.sh           # Deploy all services

     

       7
       7
       +
       #   ./scripts/deploy.sh appview   # Deploy only AppView

     

       8
       8
       +
       #   ./scripts/deploy.sh --pull    # Pull from git first, then deploy

     

       9
       9
       +
       

     

       10
       10
       +
       set -e

     

       11
       11
       +
       

     

       12
       12
       +
       SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

     

       13
       13
       +
       PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

     

       14
       14
       +
       COMPOSE_FILE="$PROJECT_DIR/docker-compose.prod.yml"

     

       15
       15
       +
       

     

       16
       16
       +
       # Colors for output

     

       17
       17
       +
       RED='\033[0;31m'

     

       18
       18
       +
       GREEN='\033[0;32m'

     

       19
       19
       +
       YELLOW='\033[1;33m'

     

       20
       20
       +
       NC='\033[0m' # No Color

     

       21
       21
       +
       

     

       22
       22
       +
       log() {

     

       23
       23
       +
           echo -e "${GREEN}[DEPLOY]${NC} $1"

     

       24
       24
       +
       }

     

       25
       25
       +
       

     

       26
       26
       +
       warn() {

     

       27
       27
       +
           echo -e "${YELLOW}[WARN]${NC} $1"

     

       28
       28
       +
       }

     

       29
       29
       +
       

     

       30
       30
       +
       error() {

     

       31
       31
       +
           echo -e "${RED}[ERROR]${NC} $1"

     

       32
       32
       +
           exit 1

     

       33
       33
       +
       }

     

       34
       34
       +
       

     

       35
       35
       +
       # Parse arguments

     

       36
       36
       +
       PULL_GIT=false

     

       37
       37
       +
       SERVICE=""

     

       38
       38
       +
       

     

       39
       39
       +
       for arg in "$@"; do

     

       40
       40
       +
           case $arg in

     

       41
       41
       +
               --pull)

     

       42
       42
       +
                   PULL_GIT=true

     

       43
       43
       +
                   ;;

     

       44
       44
       +
               *)

     

       45
       45
       +
                   SERVICE="$arg"

     

       46
       46
       +
                   ;;

     

       47
       47
       +
           esac

     

       48
       48
       +
       done

     

       49
       49
       +
       

     

       50
       50
       +
       cd "$PROJECT_DIR"

     

       51
       51
       +
       

     

       52
       52
       +
       # Load environment variables

     

       53
       53
       +
       if [ ! -f ".env.prod" ]; then

     

       54
       54
       +
           error ".env.prod not found! Copy from .env.prod.example and configure secrets."

     

       55
       55
       +
       fi

     

       56
       56
       +
       

     

       57
       57
       +
       log "Loading environment from .env.prod..."

     

       58
       58
       +
       set -a

     

       59
       59
       +
       source .env.prod

     

       60
       60
       +
       set +a

     

       61
       61
       +
       

     

       62
       62
       +
       # Optional: Pull from git

     

       63
       63
       +
       if [ "$PULL_GIT" = true ]; then

     

       64
       64
       +
           log "Pulling latest code from git..."

     

       65
       65
       +
           git fetch origin

     

       66
       66
       +
           git pull origin main

     

       67
       67
       +
       fi

     

       68
       68
       +
       

     

       69
       69
       +
       # Check database connectivity before deployment

     

       70
       70
       +
       log "Checking database connectivity..."

     

       71
       71
       +
       if docker compose -f "$COMPOSE_FILE" exec -T postgres pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" > /dev/null 2>&1; then

     

       72
       72
       +
           log "Database is ready"

     

       73
       73
       +
       else

     

       74
       74
       +
           warn "Database not ready yet - it will start with the deployment"

     

       75
       75
       +
       fi

     

       76
       76
       +
       

     

       77
       77
       +
       # Build and deploy

     

       78
       78
       +
       if [ -n "$SERVICE" ]; then

     

       79
       79
       +
           log "Building $SERVICE..."

     

       80
       80
       +
           docker compose -f "$COMPOSE_FILE" build --no-cache "$SERVICE"

     

       81
       81
       +
       

     

       82
       82
       +
           log "Deploying $SERVICE..."

     

       83
       83
       +
           docker compose -f "$COMPOSE_FILE" up -d "$SERVICE"

     

       84
       84
       +
       else

     

       85
       85
       +
           log "Building all services..."

     

       86
       86
       +
           docker compose -f "$COMPOSE_FILE" build --no-cache

     

       87
       87
       +
       

     

       88
       88
       +
           log "Deploying all services..."

     

       89
       89
       +
           docker compose -f "$COMPOSE_FILE" up -d

     

       90
       90
       +
       fi

     

       91
       91
       +
       

     

       92
       92
       +
       # Health check

     

       93
       93
       +
       log "Waiting for services to be healthy..."

     

       94
       94
       +
       sleep 10

     

       95
       95
       +
       

     

       96
       96
       +
       # Wait for database to be ready before running migrations

     

       97
       97
       +
       log "Waiting for database..."

     

       98
       98
       +
       for i in {1..30}; do

     

       99
       99
       +
           if docker compose -f "$COMPOSE_FILE" exec -T postgres pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" > /dev/null 2>&1; then

     

       100
       100
       +
               break

     

       101
       101
       +
           fi

     

       102
       102
       +
           sleep 1

     

       103
       103
       +
       done

     

       104
       104
       +
       

     

       105
       105
       +
       # Run database migrations

     

       106
       106
       +
       # The AppView runs migrations on startup, but we can also trigger them explicitly

     

       107
       107
       +
       log "Running database migrations..."

     

       108
       108
       +
       if docker compose -f "$COMPOSE_FILE" exec -T appview /app/coves-server migrate 2>/dev/null; then

     

       109
       109
       +
           log "✅ Migrations completed"

     

       110
       110
       +
       else

     

       111
       111
       +
           warn "⚠️  Migration command not available or failed - AppView will run migrations on startup"

     

       112
       112
       +
       fi

     

       113
       113
       +
       

     

       114
       114
       +
       # Check AppView health

     

       115
       115
       +
       if docker compose -f "$COMPOSE_FILE" exec -T appview wget --spider -q http://localhost:8080/xrpc/_health 2>/dev/null; then

     

       116
       116
       +
           log "✅ AppView is healthy"

     

       117
       117
       +
       else

     

       118
       118
       +
           warn "⚠️  AppView health check failed - check logs with: docker compose -f docker-compose.prod.yml logs appview"

     

       119
       119
       +
       fi

     

       120
       120
       +
       

     

       121
       121
       +
       # Check PDS health

     

       122
       122
       +
       if docker compose -f "$COMPOSE_FILE" exec -T pds wget --spider -q http://localhost:3000/xrpc/_health 2>/dev/null; then

     

       123
       123
       +
           log "✅ PDS is healthy"

     

       124
       124
       +
       else

     

       125
       125
       +
           warn "⚠️  PDS health check failed - check logs with: docker compose -f docker-compose.prod.yml logs pds"

     

       126
       126
       +
       fi

     

       127
       127
       +
       

     

       128
       128
       +
       log "Deployment complete!"

     

       129
       129
       +
       log ""

     

       130
       130
       +
       log "Useful commands:"

     

       131
       131
       +
       log "  View logs:     docker compose -f docker-compose.prod.yml logs -f"

     

       132
       132
       +
       log "  Check status:  docker compose -f docker-compose.prod.yml ps"

     

       133
       133
       +
       log "  Rollback:      docker compose -f docker-compose.prod.yml down && git checkout HEAD~1 && ./scripts/deploy.sh"

+149

scripts/generate-did-keys.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       # Generate cryptographic keys for Coves did:web DID document

     

       3
       3
       +
       #

     

       4
       4
       +
       # This script generates a secp256k1 (K-256) key pair as required by atproto.

     

       5
       5
       +
       # Reference: https://atproto.com/specs/cryptography

     

       6
       6
       +
       #

     

       7
       7
       +
       # Key format:

     

       8
       8
       +
       #   - Curve: secp256k1 (K-256) - same as Bitcoin/Ethereum

     

       9
       9
       +
       #   - Type: Multikey

     

       10
       10
       +
       #   - Encoding: publicKeyMultibase with base58btc ('z' prefix)

     

       11
       11
       +
       #   - Multicodec: 0xe7 for secp256k1 compressed public key

     

       12
       12
       +
       #

     

       13
       13
       +
       # Output:

     

       14
       14
       +
       #   - Private key (hex) for PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX

     

       15
       15
       +
       #   - Public key (multibase) for did.json publicKeyMultibase field

     

       16
       16
       +
       #   - Complete did.json file

     

       17
       17
       +
       

     

       18
       18
       +
       set -e

     

       19
       19
       +
       

     

       20
       20
       +
       SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

     

       21
       21
       +
       PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

     

       22
       22
       +
       OUTPUT_DIR="$PROJECT_DIR/static/.well-known"

     

       23
       23
       +
       

     

       24
       24
       +
       # Colors

     

       25
       25
       +
       GREEN='\033[0;32m'

     

       26
       26
       +
       YELLOW='\033[1;33m'

     

       27
       27
       +
       RED='\033[0;31m'

     

       28
       28
       +
       NC='\033[0m'

     

       29
       29
       +
       

     

       30
       30
       +
       log() { echo -e "${GREEN}[KEYGEN]${NC} $1"; }

     

       31
       31
       +
       warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }

     

       32
       32
       +
       error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

     

       33
       33
       +
       

     

       34
       34
       +
       # Check for required tools

     

       35
       35
       +
       if ! command -v openssl &> /dev/null; then

     

       36
       36
       +
           error "openssl is required but not installed"

     

       37
       37
       +
       fi

     

       38
       38
       +
       

     

       39
       39
       +
       if ! command -v python3 &> /dev/null; then

     

       40
       40
       +
           error "python3 is required for base58 encoding"

     

       41
       41
       +
       fi

     

       42
       42
       +
       

     

       43
       43
       +
       # Check for base58 library

     

       44
       44
       +
       if ! python3 -c "import base58" 2>/dev/null; then

     

       45
       45
       +
           warn "Installing base58 Python library..."

     

       46
       46
       +
           pip3 install base58 || error "Failed to install base58. Run: pip3 install base58"

     

       47
       47
       +
       fi

     

       48
       48
       +
       

     

       49
       49
       +
       log "Generating secp256k1 key pair for did:web..."

     

       50
       50
       +
       

     

       51
       51
       +
       # Generate private key

     

       52
       52
       +
       PRIVATE_KEY_PEM=$(mktemp)

     

       53
       53
       +
       openssl ecparam -name secp256k1 -genkey -noout -out "$PRIVATE_KEY_PEM" 2>/dev/null

     

       54
       54
       +
       

     

       55
       55
       +
       # Extract private key as hex (for PDS config)

     

       56
       56
       +
       PRIVATE_KEY_HEX=$(openssl ec -in "$PRIVATE_KEY_PEM" -text -noout 2>/dev/null | \

     

       57
       57
       +
           grep -A 3 "priv:" | tail -n 3 | tr -d ' :\n' | tr -d '\r')

     

       58
       58
       +
       

     

       59
       59
       +
       # Extract public key as compressed format

     

       60
       60
       +
       # OpenSSL outputs the public key, we need to get the compressed form

     

       61
       61
       +
       PUBLIC_KEY_HEX=$(openssl ec -in "$PRIVATE_KEY_PEM" -pubout -conv_form compressed -outform DER 2>/dev/null | \

     

       62
       62
       +
           tail -c 33 | xxd -p | tr -d '\n')

     

       63
       63
       +
       

     

       64
       64
       +
       # Clean up temp file

     

       65
       65
       +
       rm -f "$PRIVATE_KEY_PEM"

     

       66
       66
       +
       

     

       67
       67
       +
       # Encode public key as multibase with multicodec

     

       68
       68
       +
       # Multicodec 0xe7 = secp256k1 compressed public key

     

       69
       69
       +
       # Then base58btc encode with 'z' prefix

     

       70
       70
       +
       PUBLIC_KEY_MULTIBASE=$(python3 << EOF

     

       71
       71
       +
       import base58

     

       72
       72
       +
       

     

       73
       73
       +
       # Compressed public key bytes

     

       74
       74
       +
       pub_hex = "$PUBLIC_KEY_HEX"

     

       75
       75
       +
       pub_bytes = bytes.fromhex(pub_hex)

     

       76
       76
       +
       

     

       77
       77
       +
       # Prepend multicodec 0xe7 for secp256k1-pub

     

       78
       78
       +
       # 0xe7 as varint is just 0xe7 (single byte, < 128)

     

       79
       79
       +
       multicodec = bytes([0xe7, 0x01])  # 0xe701 for secp256k1-pub compressed

     

       80
       80
       +
       key_with_codec = multicodec + pub_bytes

     

       81
       81
       +
       

     

       82
       82
       +
       # Base58btc encode

     

       83
       83
       +
       encoded = base58.b58encode(key_with_codec).decode('ascii')

     

       84
       84
       +
       

     

       85
       85
       +
       # Add 'z' prefix for multibase

     

       86
       86
       +
       print('z' + encoded)

     

       87
       87
       +
       EOF

     

       88
       88
       +
       )

     

       89
       89
       +
       

     

       90
       90
       +
       log "Keys generated successfully!"

     

       91
       91
       +
       echo ""

     

       92
       92
       +
       echo "============================================"

     

       93
       93
       +
       echo "  PRIVATE KEY (keep secret!)"

     

       94
       94
       +
       echo "============================================"

     

       95
       95
       +
       echo ""

     

       96
       96
       +
       echo "Add this to your .env.prod file:"

     

       97
       97
       +
       echo ""

     

       98
       98
       +
       echo "PDS_ROTATION_KEY=$PRIVATE_KEY_HEX"

     

       99
       99
       +
       echo ""

     

       100
       100
       +
       echo "============================================"

     

       101
       101
       +
       echo "  PUBLIC KEY (for did.json)"

     

       102
       102
       +
       echo "============================================"

     

       103
       103
       +
       echo ""

     

       104
       104
       +
       echo "publicKeyMultibase: $PUBLIC_KEY_MULTIBASE"

     

       105
       105
       +
       echo ""

     

       106
       106
       +
       

     

       107
       107
       +
       # Generate the did.json file

     

       108
       108
       +
       log "Generating did.json..."

     

       109
       109
       +
       

     

       110
       110
       +
       mkdir -p "$OUTPUT_DIR"

     

       111
       111
       +
       

     

       112
       112
       +
       cat > "$OUTPUT_DIR/did.json" << EOF

     

       113
       113
       +
       {

     

       114
       114
       +
         "id": "did:web:coves.social",

     

       115
       115
       +
         "alsoKnownAs": ["at://coves.social"],

     

       116
       116
       +
         "verificationMethod": [

     

       117
       117
       +
           {

     

       118
       118
       +
             "id": "did:web:coves.social#atproto",

     

       119
       119
       +
             "type": "Multikey",

     

       120
       120
       +
             "controller": "did:web:coves.social",

     

       121
       121
       +
             "publicKeyMultibase": "$PUBLIC_KEY_MULTIBASE"

     

       122
       122
       +
           }

     

       123
       123
       +
         ],

     

       124
       124
       +
         "service": [

     

       125
       125
       +
           {

     

       126
       126
       +
             "id": "#atproto_pds",

     

       127
       127
       +
             "type": "AtprotoPersonalDataServer",

     

       128
       128
       +
             "serviceEndpoint": "https://coves.me"

     

       129
       129
       +
           }

     

       130
       130
       +
         ]

     

       131
       131
       +
       }

     

       132
       132
       +
       EOF

     

       133
       133
       +
       

     

       134
       134
       +
       log "Created: $OUTPUT_DIR/did.json"

     

       135
       135
       +
       echo ""

     

       136
       136
       +
       echo "============================================"

     

       137
       137
       +
       echo "  NEXT STEPS"

     

       138
       138
       +
       echo "============================================"

     

       139
       139
       +
       echo ""

     

       140
       140
       +
       echo "1. Copy the PDS_ROTATION_KEY value to your .env.prod file"

     

       141
       141
       +
       echo ""

     

       142
       142
       +
       echo "2. Verify the did.json looks correct:"

     

       143
       143
       +
       echo "   cat $OUTPUT_DIR/did.json"

     

       144
       144
       +
       echo ""

     

       145
       145
       +
       echo "3. After deployment, verify it's accessible:"

     

       146
       146
       +
       echo "   curl https://coves.social/.well-known/did.json"

     

       147
       147
       +
       echo ""

     

       148
       148
       +
       warn "IMPORTANT: Keep the private key secret! Only share the public key."

     

       149
       149
       +
       warn "The did.json file with the public key IS safe to commit to git."

+106

scripts/setup-production.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       # Coves Production Setup Script

     

       3
       3
       +
       # Run this once on a fresh server to set up everything

     

       4
       4
       +
       #

     

       5
       5
       +
       # Prerequisites:

     

       6
       6
       +
       #   - Docker and docker-compose installed

     

       7
       7
       +
       #   - Git installed

     

       8
       8
       +
       #   - .env.prod file configured

     

       9
       9
       +
       

     

       10
       10
       +
       set -e

     

       11
       11
       +
       

     

       12
       12
       +
       SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

     

       13
       13
       +
       PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

     

       14
       14
       +
       

     

       15
       15
       +
       # Colors

     

       16
       16
       +
       GREEN='\033[0;32m'

     

       17
       17
       +
       YELLOW='\033[1;33m'

     

       18
       18
       +
       RED='\033[0;31m'

     

       19
       19
       +
       NC='\033[0m'

     

       20
       20
       +
       

     

       21
       21
       +
       log() { echo -e "${GREEN}[SETUP]${NC} $1"; }

     

       22
       22
       +
       warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }

     

       23
       23
       +
       error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

     

       24
       24
       +
       

     

       25
       25
       +
       cd "$PROJECT_DIR"

     

       26
       26
       +
       

     

       27
       27
       +
       # Check prerequisites

     

       28
       28
       +
       log "Checking prerequisites..."

     

       29
       29
       +
       

     

       30
       30
       +
       if ! command -v docker &> /dev/null; then

     

       31
       31
       +
           error "Docker is not installed. Install with: curl -fsSL https://get.docker.com | sh"

     

       32
       32
       +
       fi

     

       33
       33
       +
       

     

       34
       34
       +
       if ! docker compose version &> /dev/null; then

     

       35
       35
       +
           error "docker compose is not available. Install with: apt install docker-compose-plugin"

     

       36
       36
       +
       fi

     

       37
       37
       +
       

     

       38
       38
       +
       # Check for .env.prod

     

       39
       39
       +
       if [ ! -f ".env.prod" ]; then

     

       40
       40
       +
           error ".env.prod not found! Copy from .env.prod.example and configure secrets."

     

       41
       41
       +
       fi

     

       42
       42
       +
       

     

       43
       43
       +
       # Load environment

     

       44
       44
       +
       set -a

     

       45
       45
       +
       source .env.prod

     

       46
       46
       +
       set +a

     

       47
       47
       +
       

     

       48
       48
       +
       # Create required directories

     

       49
       49
       +
       log "Creating directories..."

     

       50
       50
       +
       mkdir -p backups

     

       51
       51
       +
       mkdir -p static/.well-known

     

       52
       52
       +
       

     

       53
       53
       +
       # Check for did.json

     

       54
       54
       +
       if [ ! -f "static/.well-known/did.json" ]; then

     

       55
       55
       +
           warn "static/.well-known/did.json not found!"

     

       56
       56
       +
           warn "Run ./scripts/generate-did-keys.sh to create it."

     

       57
       57
       +
       fi

     

       58
       58
       +
       

     

       59
       59
       +
       # Note: Caddy logs are written to Docker volume (caddy-data)

     

       60
       60
       +
       # If you need host-accessible logs, uncomment and run as root:

     

       61
       61
       +
       # mkdir -p /var/log/caddy && chown 1000:1000 /var/log/caddy

     

       62
       62
       +
       

     

       63
       63
       +
       # Pull Docker images

     

       64
       64
       +
       log "Pulling Docker images..."

     

       65
       65
       +
       docker compose -f docker-compose.prod.yml pull postgres pds caddy

     

       66
       66
       +
       

     

       67
       67
       +
       # Build AppView

     

       68
       68
       +
       log "Building AppView..."

     

       69
       69
       +
       docker compose -f docker-compose.prod.yml build appview

     

       70
       70
       +
       

     

       71
       71
       +
       # Start services

     

       72
       72
       +
       log "Starting services..."

     

       73
       73
       +
       docker compose -f docker-compose.prod.yml up -d

     

       74
       74
       +
       

     

       75
       75
       +
       # Wait for PostgreSQL

     

       76
       76
       +
       log "Waiting for PostgreSQL to be ready..."

     

       77
       77
       +
       until docker compose -f docker-compose.prod.yml exec -T postgres pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB" > /dev/null 2>&1; do

     

       78
       78
       +
           sleep 2

     

       79
       79
       +
       done

     

       80
       80
       +
       log "PostgreSQL is ready!"

     

       81
       81
       +
       

     

       82
       82
       +
       # Run migrations

     

       83
       83
       +
       log "Running database migrations..."

     

       84
       84
       +
       # The AppView runs migrations on startup, but you can also run them manually:

     

       85
       85
       +
       # docker compose -f docker-compose.prod.yml exec appview /app/coves-server migrate

     

       86
       86
       +
       

     

       87
       87
       +
       # Final status

     

       88
       88
       +
       log ""

     

       89
       89
       +
       log "============================================"

     

       90
       90
       +
       log "  Coves Production Setup Complete!"

     

       91
       91
       +
       log "============================================"

     

       92
       92
       +
       log ""

     

       93
       93
       +
       log "Services running:"

     

       94
       94
       +
       docker compose -f docker-compose.prod.yml ps

     

       95
       95
       +
       log ""

     

       96
       96
       +
       log "Next steps:"

     

       97
       97
       +
       log "  1. Configure DNS for coves.social and coves.me"

     

       98
       98
       +
       log "  2. Run ./scripts/generate-did-keys.sh to create DID keys"

     

       99
       99
       +
       log "  3. Test health endpoints:"

     

       100
       100
       +
       log "     curl https://coves.social/xrpc/_health"

     

       101
       101
       +
       log "     curl https://coves.me/xrpc/_health"

     

       102
       102
       +
       log ""

     

       103
       103
       +
       log "Useful commands:"

     

       104
       104
       +
       log "  View logs:     docker compose -f docker-compose.prod.yml logs -f"

     

       105
       105
       +
       log "  Deploy update: ./scripts/deploy.sh appview"

     

       106
       106
       +
       log "  Backup DB:     ./scripts/backup.sh"

+19

static/.well-known/did.json.template

···

       1
       1
       +
       {

     

       2
       2
       +
         "id": "did:web:coves.social",

     

       3
       3
       +
         "alsoKnownAs": ["at://coves.social"],

     

       4
       4
       +
         "verificationMethod": [

     

       5
       5
       +
           {

     

       6
       6
       +
             "id": "did:web:coves.social#atproto",

     

       7
       7
       +
             "type": "Multikey",

     

       8
       8
       +
             "controller": "did:web:coves.social",

     

       9
       9
       +
             "publicKeyMultibase": "REPLACE_WITH_YOUR_PUBLIC_KEY"

     

       10
       10
       +
           }

     

       11
       11
       +
         ],

     

       12
       12
       +
         "service": [

     

       13
       13
       +
           {

     

       14
       14
       +
             "id": "#atproto_pds",

     

       15
       15
       +
             "type": "AtprotoPersonalDataServer",

     

       16
       16
       +
             "serviceEndpoint": "https://coves.me"

     

       17
       17
       +
           }

     

       18
       18
       +
         ]

     

       19
       19
       +
       }

+18

static/client-metadata.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "client_id": "https://coves.social/client-metadata.json",

     

       3
       3
       +
         "client_name": "Coves",

     

       4
       4
       +
         "client_uri": "https://coves.social",

     

       5
       5
       +
         "logo_uri": "https://coves.social/logo.png",

     

       6
       6
       +
         "tos_uri": "https://coves.social/terms",

     

       7
       7
       +
         "policy_uri": "https://coves.social/privacy",

     

       8
       8
       +
         "redirect_uris": [

     

       9
       9
       +
           "https://coves.social/oauth/callback",

     

       10
       10
       +
           "social.coves:/oauth/callback"

     

       11
       11
       +
         ],

     

       12
       12
       +
         "scope": "atproto transition:generic",

     

       13
       13
       +
         "grant_types": ["authorization_code", "refresh_token"],

     

       14
       14
       +
         "response_types": ["code"],

     

       15
       15
       +
         "application_type": "native",

     

       16
       16
       +
         "token_endpoint_auth_method": "none",

     

       17
       17
       +
         "dpop_bound_access_tokens": true

     

       18
       18
       +
       }

+97

static/oauth/callback.html

···

       1
       1
       +
       <!DOCTYPE html>

     

       2
       2
       +
       <html>

     

       3
       3
       +
       <head>

     

       4
       4
       +
         <meta charset="utf-8">

     

       5
       5
       +
         <meta name="viewport" content="width=device-width, initial-scale=1">

     

       6
       6
       +
         <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'">

     

       7
       7
       +
         <title>Authorization Successful - Coves</title>

     

       8
       8
       +
         <style>

     

       9
       9
       +
           body {

     

       10
       10
       +
             font-family: system-ui, -apple-system, sans-serif;

     

       11
       11
       +
             display: flex;

     

       12
       12
       +
             align-items: center;

     

       13
       13
       +
             justify-content: center;

     

       14
       14
       +
             min-height: 100vh;

     

       15
       15
       +
             margin: 0;

     

       16
       16
       +
             background: #f5f5f5;

     

       17
       17
       +
           }

     

       18
       18
       +
           .container {

     

       19
       19
       +
             text-align: center;

     

       20
       20
       +
             padding: 2rem;

     

       21
       21
       +
             background: white;

     

       22
       22
       +
             border-radius: 8px;

     

       23
       23
       +
             box-shadow: 0 2px 8px rgba(0,0,0,0.1);

     

       24
       24
       +
             max-width: 400px;

     

       25
       25
       +
           }

     

       26
       26
       +
           .success { color: #22c55e; font-size: 3rem; margin-bottom: 1rem; }

     

       27
       27
       +
           h1 { margin: 0 0 0.5rem; color: #1f2937; font-size: 1.5rem; }

     

       28
       28
       +
           p { color: #6b7280; margin: 0.5rem 0; }

     

       29
       29
       +
           a {

     

       30
       30
       +
             display: inline-block;

     

       31
       31
       +
             margin-top: 1rem;

     

       32
       32
       +
             padding: 0.75rem 1.5rem;

     

       33
       33
       +
             background: #3b82f6;

     

       34
       34
       +
             color: white;

     

       35
       35
       +
             text-decoration: none;

     

       36
       36
       +
             border-radius: 6px;

     

       37
       37
       +
             font-weight: 500;

     

       38
       38
       +
           }

     

       39
       39
       +
           a:hover { background: #2563eb; }

     

       40
       40
       +
         </style>

     

       41
       41
       +
       </head>

     

       42
       42
       +
       <body>

     

       43
       43
       +
         <div class="container">

     

       44
       44
       +
           <div class="success">✓</div>

     

       45
       45
       +
           <h1>Authorization Successful!</h1>

     

       46
       46
       +
           <p id="status">Returning to Coves...</p>

     

       47
       47
       +
           <a href="#" id="manualLink">Open Coves</a>

     

       48
       48
       +
         </div>

     

       49
       49
       +
         <script>

     

       50
       50
       +
           (function() {

     

       51
       51
       +
             // Parse and sanitize query params - only allow expected OAuth parameters

     

       52
       52
       +
             const urlParams = new URLSearchParams(window.location.search);

     

       53
       53
       +
             const safeParams = new URLSearchParams();

     

       54
       54
       +
       

     

       55
       55
       +
             // Whitelist only expected OAuth callback parameters

     

       56
       56
       +
             const code = urlParams.get('code');

     

       57
       57
       +
             const state = urlParams.get('state');

     

       58
       58
       +
             const error = urlParams.get('error');

     

       59
       59
       +
             const errorDescription = urlParams.get('error_description');

     

       60
       60
       +
             const iss = urlParams.get('iss');

     

       61
       61
       +
       

     

       62
       62
       +
             if (code) safeParams.set('code', code);

     

       63
       63
       +
             if (state) safeParams.set('state', state);

     

       64
       64
       +
             if (error) safeParams.set('error', error);

     

       65
       65
       +
             if (errorDescription) safeParams.set('error_description', errorDescription);

     

       66
       66
       +
             if (iss) safeParams.set('iss', iss);

     

       67
       67
       +
       

     

       68
       68
       +
             const sanitizedQuery = safeParams.toString() ? '?' + safeParams.toString() : '';

     

       69
       69
       +
       

     

       70
       70
       +
             const userAgent = navigator.userAgent || '';

     

       71
       71
       +
             const isAndroid = /Android/i.test(userAgent);

     

       72
       72
       +
       

     

       73
       73
       +
             // Build deep link based on platform

     

       74
       74
       +
             let deepLink;

     

       75
       75
       +
             if (isAndroid) {

     

       76
       76
       +
               // Android: Intent URL format

     

       77
       77
       +
               const pathAndQuery = '/oauth/callback' + sanitizedQuery;

     

       78
       78
       +
               deepLink = 'intent:/' + pathAndQuery + '#Intent;scheme=social.coves;package=social.coves;end';

     

       79
       79
       +
             } else {

     

       80
       80
       +
               // iOS: Custom scheme

     

       81
       81
       +
               deepLink = 'social.coves:/oauth/callback' + sanitizedQuery;

     

       82
       82
       +
             }

     

       83
       83
       +
       

     

       84
       84
       +
             // Update manual link

     

       85
       85
       +
             document.getElementById('manualLink').href = deepLink;

     

       86
       86
       +
       

     

       87
       87
       +
             // Attempt automatic redirect

     

       88
       88
       +
             window.location.href = deepLink;

     

       89
       89
       +
       

     

       90
       90
       +
             // Update status after 2 seconds if redirect didn't work

     

       91
       91
       +
             setTimeout(function() {

     

       92
       92
       +
               document.getElementById('status').textContent = 'Click the button above to continue';

     

       93
       93
       +
             }, 2000);

     

       94
       94
       +
           })();

     

       95
       95
       +
         </script>

     

       96
       96
       +
       </body>

     

       97
       97
       +
       </html>

+2 -1

Dockerfile

···

       42
       42
        
       COPY --from=builder /build/coves-server /app/coves-server

     

       43
       43
        
       

     

       44
       44
        
       # Copy migrations (needed for goose)

     

       45
       45
       -
       COPY --from=builder /build/internal/db/migrations /app/migrations

     

       45
       45
       +
       # Must maintain path structure as app looks for internal/db/migrations

     

       46
       46
       +
       COPY --from=builder /build/internal/db/migrations /app/internal/db/migrations

     

       46
       47
        
       

     

       47
       48
        
       # Set ownership

     

       48
       49
        
       RUN chown -R coves:coves /app

+187

scripts/derive-did-from-key.sh

···

       1
       1
       +
       #!/bin/bash

     

       2
       2
       +
       # Derive public key from existing PDS_ROTATION_KEY and create did.json

     

       3
       3
       +
       #

     

       4
       4
       +
       # This script takes your existing private key and derives the public key from it.

     

       5
       5
       +
       # Use this if you already have a PDS running with a rotation key but need to

     

       6
       6
       +
       # create/fix the did.json file.

     

       7
       7
       +
       #

     

       8
       8
       +
       # Usage: ./scripts/derive-did-from-key.sh

     

       9
       9
       +
       

     

       10
       10
       +
       set -e

     

       11
       11
       +
       

     

       12
       12
       +
       SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

     

       13
       13
       +
       PROJECT_DIR="$(dirname "$SCRIPT_DIR")"

     

       14
       14
       +
       OUTPUT_DIR="$PROJECT_DIR/static/.well-known"

     

       15
       15
       +
       

     

       16
       16
       +
       # Colors

     

       17
       17
       +
       GREEN='\033[0;32m'

     

       18
       18
       +
       YELLOW='\033[1;33m'

     

       19
       19
       +
       RED='\033[0;31m'

     

       20
       20
       +
       NC='\033[0m'

     

       21
       21
       +
       

     

       22
       22
       +
       log() { echo -e "${GREEN}[DERIVE]${NC} $1"; }

     

       23
       23
       +
       warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }

     

       24
       24
       +
       error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

     

       25
       25
       +
       

     

       26
       26
       +
       # Check for required tools

     

       27
       27
       +
       if ! command -v openssl &> /dev/null; then

     

       28
       28
       +
           error "openssl is required but not installed"

     

       29
       29
       +
       fi

     

       30
       30
       +
       

     

       31
       31
       +
       if ! command -v python3 &> /dev/null; then

     

       32
       32
       +
           error "python3 is required for base58 encoding"

     

       33
       33
       +
       fi

     

       34
       34
       +
       

     

       35
       35
       +
       # Check for base58 library

     

       36
       36
       +
       if ! python3 -c "import base58" 2>/dev/null; then

     

       37
       37
       +
           warn "Installing base58 Python library..."

     

       38
       38
       +
           pip3 install base58 || error "Failed to install base58. Run: pip3 install base58"

     

       39
       39
       +
       fi

     

       40
       40
       +
       

     

       41
       41
       +
       # Load environment to get the existing key

     

       42
       42
       +
       if [ -f "$PROJECT_DIR/.env.prod" ]; then

     

       43
       43
       +
           source "$PROJECT_DIR/.env.prod"

     

       44
       44
       +
       elif [ -f "$PROJECT_DIR/.env" ]; then

     

       45
       45
       +
           source "$PROJECT_DIR/.env"

     

       46
       46
       +
       else

     

       47
       47
       +
           error "No .env.prod or .env file found"

     

       48
       48
       +
       fi

     

       49
       49
       +
       

     

       50
       50
       +
       if [ -z "$PDS_ROTATION_KEY" ]; then

     

       51
       51
       +
           error "PDS_ROTATION_KEY not found in environment"

     

       52
       52
       +
       fi

     

       53
       53
       +
       

     

       54
       54
       +
       # Validate key format (should be 64 hex chars)

     

       55
       55
       +
       if [[ ! "$PDS_ROTATION_KEY" =~ ^[0-9a-fA-F]{64}$ ]]; then

     

       56
       56
       +
           error "PDS_ROTATION_KEY is not a valid 64-character hex string"

     

       57
       57
       +
       fi

     

       58
       58
       +
       

     

       59
       59
       +
       log "Deriving public key from existing PDS_ROTATION_KEY..."

     

       60
       60
       +
       

     

       61
       61
       +
       # Create a temporary PEM file from the hex private key

     

       62
       62
       +
       TEMP_DIR=$(mktemp -d)

     

       63
       63
       +
       PRIVATE_KEY_HEX="$PDS_ROTATION_KEY"

     

       64
       64
       +
       

     

       65
       65
       +
       # Convert hex private key to PEM format

     

       66
       66
       +
       # secp256k1 curve OID: 1.3.132.0.10

     

       67
       67
       +
       python3 > "$TEMP_DIR/private.pem" << EOF

     

       68
       68
       +
       import binascii

     

       69
       69
       +
       

     

       70
       70
       +
       # Private key in hex

     

       71
       71
       +
       priv_hex = "$PRIVATE_KEY_HEX"

     

       72
       72
       +
       priv_bytes = binascii.unhexlify(priv_hex)

     

       73
       73
       +
       

     

       74
       74
       +
       # secp256k1 OID

     

       75
       75
       +
       oid = bytes([0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x0a])

     

       76
       76
       +
       

     

       77
       77
       +
       # Build the EC private key structure

     

       78
       78
       +
       # SEQUENCE { version INTEGER, privateKey OCTET STRING, [0] OID, [1] publicKey }

     

       79
       79
       +
       # We'll use a simpler approach: just the private key with curve params

     

       80
       80
       +
       

     

       81
       81
       +
       # EC PARAMETERS for secp256k1

     

       82
       82
       +
       ec_params = bytes([

     

       83
       83
       +
           0x30, 0x07,  # SEQUENCE, 7 bytes

     

       84
       84
       +
           0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x0a  # OID for secp256k1

     

       85
       85
       +
       ])

     

       86
       86
       +
       

     

       87
       87
       +
       # EC PRIVATE KEY structure

     

       88
       88
       +
       # SEQUENCE { version, privateKey, [0] parameters }

     

       89
       89
       +
       inner = bytes([0x02, 0x01, 0x01])  # version = 1

     

       90
       90
       +
       inner += bytes([0x04, 0x20]) + priv_bytes  # OCTET STRING with 32-byte key

     

       91
       91
       +
       inner += bytes([0xa0, 0x07]) + bytes([0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x0a])  # [0] OID

     

       92
       92
       +
       

     

       93
       93
       +
       # Wrap in SEQUENCE

     

       94
       94
       +
       key_der = bytes([0x30, len(inner)]) + inner

     

       95
       95
       +
       

     

       96
       96
       +
       # Base64 encode

     

       97
       97
       +
       import base64

     

       98
       98
       +
       key_b64 = base64.b64encode(key_der).decode('ascii')

     

       99
       99
       +
       

     

       100
       100
       +
       # Format as PEM

     

       101
       101
       +
       print("-----BEGIN EC PRIVATE KEY-----")

     

       102
       102
       +
       for i in range(0, len(key_b64), 64):

     

       103
       103
       +
           print(key_b64[i:i+64])

     

       104
       104
       +
       print("-----END EC PRIVATE KEY-----")

     

       105
       105
       +
       EOF

     

       106
       106
       +
       

     

       107
       107
       +
       # Extract the compressed public key

     

       108
       108
       +
       PUBLIC_KEY_HEX=$(openssl ec -in "$TEMP_DIR/private.pem" -pubout -conv_form compressed -outform DER 2>/dev/null | \

     

       109
       109
       +
           tail -c 33 | xxd -p | tr -d '\n')

     

       110
       110
       +
       

     

       111
       111
       +
       # Clean up

     

       112
       112
       +
       rm -rf "$TEMP_DIR"

     

       113
       113
       +
       

     

       114
       114
       +
       if [ -z "$PUBLIC_KEY_HEX" ] || [ ${#PUBLIC_KEY_HEX} -ne 66 ]; then

     

       115
       115
       +
           error "Failed to derive public key. Got: $PUBLIC_KEY_HEX"

     

       116
       116
       +
       fi

     

       117
       117
       +
       

     

       118
       118
       +
       log "Derived public key: ${PUBLIC_KEY_HEX:0:8}...${PUBLIC_KEY_HEX: -8}"

     

       119
       119
       +
       

     

       120
       120
       +
       # Encode public key as multibase with multicodec

     

       121
       121
       +
       PUBLIC_KEY_MULTIBASE=$(python3 << EOF

     

       122
       122
       +
       import base58

     

       123
       123
       +
       

     

       124
       124
       +
       # Compressed public key bytes

     

       125
       125
       +
       pub_hex = "$PUBLIC_KEY_HEX"

     

       126
       126
       +
       pub_bytes = bytes.fromhex(pub_hex)

     

       127
       127
       +
       

     

       128
       128
       +
       # Prepend multicodec 0xe7 for secp256k1-pub

     

       129
       129
       +
       # 0xe7 as varint is just 0xe7 (single byte, < 128)

     

       130
       130
       +
       multicodec = bytes([0xe7, 0x01])  # 0xe701 for secp256k1-pub compressed

     

       131
       131
       +
       key_with_codec = multicodec + pub_bytes

     

       132
       132
       +
       

     

       133
       133
       +
       # Base58btc encode

     

       134
       134
       +
       encoded = base58.b58encode(key_with_codec).decode('ascii')

     

       135
       135
       +
       

     

       136
       136
       +
       # Add 'z' prefix for multibase

     

       137
       137
       +
       print('z' + encoded)

     

       138
       138
       +
       EOF

     

       139
       139
       +
       )

     

       140
       140
       +
       

     

       141
       141
       +
       log "Public key multibase: $PUBLIC_KEY_MULTIBASE"

     

       142
       142
       +
       

     

       143
       143
       +
       # Generate the did.json file

     

       144
       144
       +
       log "Generating did.json..."

     

       145
       145
       +
       

     

       146
       146
       +
       mkdir -p "$OUTPUT_DIR"

     

       147
       147
       +
       

     

       148
       148
       +
       cat > "$OUTPUT_DIR/did.json" << EOF

     

       149
       149
       +
       {

     

       150
       150
       +
         "id": "did:web:coves.social",

     

       151
       151
       +
         "alsoKnownAs": ["at://coves.social"],

     

       152
       152
       +
         "verificationMethod": [

     

       153
       153
       +
           {

     

       154
       154
       +
             "id": "did:web:coves.social#atproto",

     

       155
       155
       +
             "type": "Multikey",

     

       156
       156
       +
             "controller": "did:web:coves.social",

     

       157
       157
       +
             "publicKeyMultibase": "$PUBLIC_KEY_MULTIBASE"

     

       158
       158
       +
           }

     

       159
       159
       +
         ],

     

       160
       160
       +
         "service": [

     

       161
       161
       +
           {

     

       162
       162
       +
             "id": "#atproto_pds",

     

       163
       163
       +
             "type": "AtprotoPersonalDataServer",

     

       164
       164
       +
             "serviceEndpoint": "https://coves.me"

     

       165
       165
       +
           }

     

       166
       166
       +
         ]

     

       167
       167
       +
       }

     

       168
       168
       +
       EOF

     

       169
       169
       +
       

     

       170
       170
       +
       log "Created: $OUTPUT_DIR/did.json"

     

       171
       171
       +
       echo ""

     

       172
       172
       +
       echo "============================================"

     

       173
       173
       +
       echo "  DID Document Generated Successfully!"

     

       174
       174
       +
       echo "============================================"

     

       175
       175
       +
       echo ""

     

       176
       176
       +
       echo "Public key multibase: $PUBLIC_KEY_MULTIBASE"

     

       177
       177
       +
       echo ""

     

       178
       178
       +
       echo "Next steps:"

     

       179
       179
       +
       echo "  1. Copy this file to your production server:"

     

       180
       180
       +
       echo "     scp $OUTPUT_DIR/did.json user@server:/opt/coves/static/.well-known/"

     

       181
       181
       +
       echo ""

     

       182
       182
       +
       echo "  2. Or if running on production, restart Caddy:"

     

       183
       183
       +
       echo "     docker compose -f docker-compose.prod.yml restart caddy"

     

       184
       184
       +
       echo ""

     

       185
       185
       +
       echo "  3. Verify it's accessible:"

     

       186
       186
       +
       echo "     curl https://coves.social/.well-known/did.json"

     

       187
       187
       +
       echo ""

+3 -2

internal/api/routes/community.go

···

       10
       10
        
       

     

       11
       11
        
       // RegisterCommunityRoutes registers community-related XRPC endpoints on the router

     

       12
       12
        
       // Implements social.coves.community.* lexicon endpoints

     

       13
       13
       -
       func RegisterCommunityRoutes(r chi.Router, service communities.Service, authMiddleware *middleware.AtProtoAuthMiddleware) {

     

       13
       13
       +
       // allowedCommunityCreators restricts who can create communities. If empty, anyone can create.

     

       14
       14
       +
       func RegisterCommunityRoutes(r chi.Router, service communities.Service, authMiddleware *middleware.AtProtoAuthMiddleware, allowedCommunityCreators []string) {

     

       14
       15
        
       	// Initialize handlers

     

       15
       15
       -
       	createHandler := community.NewCreateHandler(service)

     

       16
       16
       +
       	createHandler := community.NewCreateHandler(service, allowedCommunityCreators)

     

       16
       17
        
       	getHandler := community.NewGetHandler(service)

     

       17
       18
        
       	updateHandler := community.NewUpdateHandler(service)

     

       18
       19
        
       	listHandler := community.NewListHandler(service)

+2 -3

internal/api/handlers/community/block.go

···

       1
       1
        
       package community

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/middleware"

     

       5
       5
       +
       	"Coves/internal/core/communities"

     

       4
       6
        
       	"encoding/json"

     

       5
       7
        
       	"log"

     

       6
       8
        
       	"net/http"

     

       7
       7
       -
       

     

       8
       8
       -
       	"Coves/internal/api/middleware"

     

       9
       9
       -
       	"Coves/internal/core/communities"

     

       10
       9
        
       )

     

       11
       10
        
       

     

       12
       11
        
       // BlockHandler handles community blocking operations

+1 -2

internal/api/handlers/community/list.go

···

       1
       1
        
       package community

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/core/communities"

     

       4
       5
        
       	"encoding/json"

     

       5
       6
        
       	"net/http"

     

       6
       7
        
       	"strconv"

     

       7
       7
       -
       

     

       8
       8
       -
       	"Coves/internal/core/communities"

     

       9
       8
        
       )

     

       10
       9
        
       

     

       11
       10
        
       // ListHandler handles listing communities

+2 -3

internal/atproto/jetstream/comment_consumer.go

···

       1
       1
        
       package jetstream

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/utils"

     

       5
       5
       +
       	"Coves/internal/core/comments"

     

       4
       6
        
       	"context"

     

       5
       7
        
       	"database/sql"

     

       6
       8
        
       	"encoding/json"

     
···

       9
       11
        
       	"strings"

     

       10
       12
        
       	"time"

     

       11
       13
        
       

     

       12
       12
       -
       	"Coves/internal/atproto/utils"

     

       13
       13
       -
       	"Coves/internal/core/comments"

     

       14
       14
       -
       

     

       15
       14
        
       	"github.com/lib/pq"

     

       16
       15
        
       )

     

       17
       16

+3 -4

internal/atproto/jetstream/community_consumer.go

···

       1
       1
        
       package jetstream

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/identity"

     

       5
       5
       +
       	"Coves/internal/atproto/utils"

     

       6
       6
       +
       	"Coves/internal/core/communities"

     

       4
       7
        
       	"context"

     

       5
       8
        
       	"encoding/json"

     

       6
       9
        
       	"fmt"

     
···

       9
       12
        
       	"strings"

     

       10
       13
        
       	"time"

     

       11
       14
        
       

     

       12
       12
       -
       	"Coves/internal/atproto/identity"

     

       13
       13
       -
       	"Coves/internal/atproto/utils"

     

       14
       14
       -
       	"Coves/internal/core/communities"

     

       15
       15
       -
       

     

       16
       15
        
       	lru "github.com/hashicorp/golang-lru/v2"

     

       17
       16
        
       	"golang.org/x/net/publicsuffix"

     

       18
       17
        
       	"golang.org/x/time/rate"

+1 -2

internal/core/communities/service.go

···

       1
       1
        
       package communities

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/utils"

     

       4
       5
        
       	"bytes"

     

       5
       6
        
       	"context"

     

       6
       7
        
       	"encoding/json"

     
···

       13
       14
        
       	"strings"

     

       14
       15
        
       	"sync"

     

       15
       16
        
       	"time"

     

       16
       16
       -
       

     

       17
       17
       -
       	"Coves/internal/atproto/utils"

     

       18
       17
        
       )

     

       19
       18
        
       

     

       20
       19
        
       // Community handle validation regex (DNS-valid handle: name.community.instance.com)

+2 -4

internal/db/postgres/community_repo.go

···

       1
       1
        
       package postgres

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/core/communities"

     

       4
       5
        
       	"context"

     

       5
       6
        
       	"database/sql"

     

       6
       7
        
       	"fmt"

     

       7
       8
        
       	"log"

     

       8
       9
        
       	"strings"

     

       9
       10
        
       

     

       10
       10
       -
       	"Coves/internal/core/communities"

     

       11
       11
       -
       

     

       12
       11
        
       	"github.com/lib/pq"

     

       13
       12
        
       )

     

       14
       13
        
       

     
···

       369
       368
        
       	}

     

       370
       369
        
       

     

       371
       370
        
       	// Build sort clause - map sort enum to DB columns

     

       372
       372
       -
       	sortColumn := "subscriber_count" // default: popular

     

       373
       373
       -
       	sortOrder := "DESC"

     

       371
       371
       +
       	var sortColumn, sortOrder string

     

       374
       372
        
       

     

       375
       373
        
       	switch req.Sort {

     

       376
       374
        
       	case "popular":

+7 -8

tests/e2e/error_recovery_test.go

···

       1
       1
        
       package e2e

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/identity"

     

       5
       5
       +
       	"Coves/internal/atproto/jetstream"

     

       6
       6
       +
       	"Coves/internal/core/users"

     

       7
       7
       +
       	"Coves/internal/db/postgres"

     

       4
       8
        
       	"context"

     

       5
       9
        
       	"database/sql"

     

       6
       10
        
       	"fmt"

     
···

       12
       16
        
       	"testing"

     

       13
       17
        
       	"time"

     

       14
       18
        
       

     

       15
       15
       -
       	"Coves/internal/atproto/identity"

     

       16
       16
       -
       	"Coves/internal/atproto/jetstream"

     

       17
       17
       -
       	"Coves/internal/core/users"

     

       18
       18
       -
       	"Coves/internal/db/postgres"

     

       19
       19
       -
       

     

       20
       19
        
       	_ "github.com/lib/pq"

     

       21
       20
        
       	"github.com/pressly/goose/v3"

     

       22
       21
        
       )

     
···

       138
       137
        
       

     

       139
       138
        
       	testCases := []struct {

     

       140
       139
        
       		name      string

     

       141
       141
       -
       		event     jetstream.JetstreamEvent

     

       142
       140
        
       		shouldLog string

     

       141
       141
       +
       		event     jetstream.JetstreamEvent

     

       143
       142
        
       	}{

     

       144
       143
        
       		{

     

       145
       144
        
       			name: "Nil identity data",

     
···

       348
       347
        
       		if shouldFail.Load() {

     

       349
       348
        
       			t.Logf("Mock PDS: Simulating unavailability (request #%d)", requestCount.Load())

     

       350
       349
        
       			w.WriteHeader(http.StatusServiceUnavailable)

     

       351
       351
       -
       			w.Write([]byte(`{"error":"ServiceUnavailable","message":"PDS temporarily unavailable"}`))

     

       350
       350
       +
       			_, _ = w.Write([]byte(`{"error":"ServiceUnavailable","message":"PDS temporarily unavailable"}`))

     

       352
       351
        
       			return

     

       353
       352
        
       		}

     

       354
       353
        
       

     

       355
       354
        
       		t.Logf("Mock PDS: Serving request successfully (request #%d)", requestCount.Load())

     

       356
       355
        
       		// Simulate successful PDS response

     

       357
       356
        
       		w.WriteHeader(http.StatusOK)

     

       358
       358
       -
       		w.Write([]byte(`{"did":"did:plc:pdstest123","handle":"pds.test"}`))

     

       357
       357
       +
       		_, _ = w.Write([]byte(`{"did":"did:plc:pdstest123","handle":"pds.test"}`))

     

       359
       358
        
       	}))

     

       360
       359
        
       	defer mockPDS.Close()

     

       361
       360

+13 -14

tests/integration/blob_upload_e2e_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/identity"

     

       5
       5
       +
       	"Coves/internal/atproto/jetstream"

     

       6
       6
       +
       	"Coves/internal/core/blobs"

     

       7
       7
       +
       	"Coves/internal/core/communities"

     

       8
       8
       +
       	"Coves/internal/core/posts"

     

       9
       9
       +
       	"Coves/internal/core/users"

     

       10
       10
       +
       	"Coves/internal/db/postgres"

     

       4
       11
        
       	"bytes"

     

       5
       12
        
       	"context"

     

       6
       13
        
       	"encoding/json"

     
···

       15
       22
        
       	"testing"

     

       16
       23
        
       	"time"

     

       17
       24
        
       

     

       18
       18
       -
       	"Coves/internal/atproto/identity"

     

       19
       19
       -
       	"Coves/internal/atproto/jetstream"

     

       20
       20
       -
       	"Coves/internal/core/blobs"

     

       21
       21
       -
       	"Coves/internal/core/communities"

     

       22
       22
       -
       	"Coves/internal/core/posts"

     

       23
       23
       -
       	"Coves/internal/core/users"

     

       24
       24
       -
       	"Coves/internal/db/postgres"

     

       25
       25
       -
       

     

       26
       25
        
       	"github.com/stretchr/testify/assert"

     

       27
       26
        
       	"github.com/stretchr/testify/require"

     

       28
       27
        
       )

     
···

       49
       48
        
       	if err != nil {

     

       50
       49
        
       		t.Skipf("PDS not running at %s: %v. Run 'make dev-up' to start PDS.", pdsURL, err)

     

       51
       50
        
       	}

     

       52
       52
       -
       	defer healthResp.Body.Close()

     

       51
       51
       +
       	defer func() { _ = healthResp.Body.Close() }()

     

       53
       52
        
       	if healthResp.StatusCode != http.StatusOK {

     

       54
       53
        
       		t.Skipf("PDS health check failed at %s: status %d", pdsURL, healthResp.StatusCode)

     

       55
       54
        
       	}

     
···

       357
       356
        
       	if err != nil {

     

       358
       357
        
       		t.Skipf("PDS not running at %s: %v. Run 'make dev-up' to start PDS.", pdsURL, err)

     

       359
       358
        
       	}

     

       360
       360
       -
       	defer healthResp.Body.Close()

     

       359
       359
       +
       	defer func() { _ = healthResp.Body.Close() }()

     

       361
       360
        
       	if healthResp.StatusCode != http.StatusOK {

     

       362
       361
        
       		t.Skipf("PDS health check failed at %s: status %d", pdsURL, healthResp.StatusCode)

     

       363
       362
        
       	}

     
···

       545
       544
        
       

     

       546
       545
        
       	t.Run("Accept matching image formats with correct MIME types", func(t *testing.T) {

     

       547
       546
        
       		testCases := []struct {

     

       547
       547
       +
       			createFunc func(*testing.T, int, int, color.Color) []byte

     

       548
       548
        
       			format     string

     

       549
       549
        
       			mimeType   string

     

       550
       550
       -
       			createFunc func(*testing.T, int, int, color.Color) []byte

     

       551
       550
        
       		}{

     

       552
       552
       -
       			{"PNG", "image/png", createTestPNG},

     

       553
       553
       -
       			{"JPEG", "image/jpeg", createTestJPEG},

     

       551
       551
       +
       			{createTestPNG, "PNG", "image/png"},

     

       552
       552
       +
       			{createTestJPEG, "JPEG", "image/jpeg"},

     

       554
       553
        
       			// Note: WebP requires external library (golang.org/x/image/webp)

     

       555
       554
        
       			// For now, we test that the MIME type is accepted even with PNG data

     

       556
       555
        
       			// In production, actual WebP validation would happen at PDS

     

       557
       557
       -
       			{"WebP (MIME only)", "image/webp", createTestPNG},

     

       556
       556
       +
       			{createTestPNG, "WebP (MIME only)", "image/webp"},

     

       558
       557
        
       		}

     

       559
       558
        
       

     

       560
       559
        
       		for _, tc := range testCases {

+14 -14

tests/integration/block_handle_resolution_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/handlers/community"

     

       5
       5
       +
       	"Coves/internal/api/middleware"

     

       6
       6
       +
       	"Coves/internal/core/communities"

     

       4
       7
        
       	"bytes"

     

       5
       8
        
       	"context"

     

       6
       9
        
       	"encoding/json"

     
···

       9
       12
        
       	"net/http/httptest"

     

       10
       13
        
       	"testing"

     

       11
       14
        
       

     

       12
       12
       -
       	"Coves/internal/api/handlers/community"

     

       13
       13
       -
       	"Coves/internal/api/middleware"

     

       14
       14
       -
       	"Coves/internal/core/communities"

     

       15
       15
        
       	postgresRepo "Coves/internal/db/postgres"

     

       16
       16
        
       )

     

       17
       17
        
       

     
···

       73
       73
        
       		// We expect 401 (no auth) but verify the error is NOT "Community not found"

     

       74
       74
        
       		// If handle resolution worked, we'd get past that validation

     

       75
       75
        
       		resp := w.Result()

     

       76
       76
       -
       		defer resp.Body.Close()

     

       76
       76
       +
       		defer func() { _ = resp.Body.Close() }()

     

       77
       77
        
       

     

       78
       78
        
       		if resp.StatusCode == http.StatusNotFound {

     

       79
       79
        
       			t.Errorf("Handle resolution failed - got 404 CommunityNotFound")

     
···

       82
       82
        
       		// Expected: 401 Unauthorized (because we didn't add auth context)

     

       83
       83
        
       		if resp.StatusCode != http.StatusUnauthorized {

     

       84
       84
        
       			var errorResp map[string]interface{}

     

       85
       85
       -
       			json.NewDecoder(resp.Body).Decode(&errorResp)

     

       85
       85
       +
       			_ = json.NewDecoder(resp.Body).Decode(&errorResp)

     

       86
       86
        
       			t.Logf("Response status: %d, body: %+v", resp.StatusCode, errorResp)

     

       87
       87
        
       		}

     

       88
       88
        
       	})

     
···

       100
       100
        
       		blockHandler.HandleBlock(w, req)

     

       101
       101
        
       

     

       102
       102
        
       		resp := w.Result()

     

       103
       103
       -
       		defer resp.Body.Close()

     

       103
       103
       +
       		defer func() { _ = resp.Body.Close() }()

     

       104
       104
        
       

     

       105
       105
        
       		if resp.StatusCode == http.StatusNotFound {

     

       106
       106
        
       			t.Errorf("@-prefixed handle resolution failed - got 404 CommunityNotFound")

     
···

       121
       121
        
       		blockHandler.HandleBlock(w, req)

     

       122
       122
        
       

     

       123
       123
        
       		resp := w.Result()

     

       124
       124
       -
       		defer resp.Body.Close()

     

       124
       124
       +
       		defer func() { _ = resp.Body.Close() }()

     

       125
       125
        
       

     

       126
       126
        
       		if resp.StatusCode == http.StatusNotFound {

     

       127
       127
        
       			t.Errorf("Scoped format resolution failed - got 404 CommunityNotFound")

     
···

       141
       141
        
       		blockHandler.HandleBlock(w, req)

     

       142
       142
        
       

     

       143
       143
        
       		resp := w.Result()

     

       144
       144
       -
       		defer resp.Body.Close()

     

       144
       144
       +
       		defer func() { _ = resp.Body.Close() }()

     

       145
       145
        
       

     

       146
       146
        
       		if resp.StatusCode == http.StatusNotFound {

     

       147
       147
        
       			t.Errorf("DID resolution failed - got 404 CommunityNotFound")

     
···

       202
       202
        
       				blockHandler.HandleBlock(w, req)

     

       203
       203
        
       

     

       204
       204
        
       				resp := w.Result()

     

       205
       205
       -
       				defer resp.Body.Close()

     

       205
       205
       +
       				defer func() { _ = resp.Body.Close() }()

     

       206
       206
        
       

     

       207
       207
        
       				// Should return 400 Bad Request for validation errors

     

       208
       208
        
       				if resp.StatusCode != http.StatusBadRequest {

     
···

       210
       210
        
       				}

     

       211
       211
        
       

     

       212
       212
        
       				var errorResp map[string]interface{}

     

       213
       213
       -
       				json.NewDecoder(resp.Body).Decode(&errorResp)

     

       213
       213
       +
       				_ = json.NewDecoder(resp.Body).Decode(&errorResp)

     

       214
       214
        
       

     

       215
       215
        
       				if errorCode, ok := errorResp["error"].(string); !ok || errorCode != "InvalidRequest" {

     

       216
       216
        
       					t.Errorf("Expected error code 'InvalidRequest', got %v", errorResp["error"])

     
···

       242
       242
        
       		blockHandler.HandleBlock(w, req)

     

       243
       243
        
       

     

       244
       244
        
       		resp := w.Result()

     

       245
       245
       -
       		defer resp.Body.Close()

     

       245
       245
       +
       		defer func() { _ = resp.Body.Close() }()

     

       246
       246
        
       

     

       247
       247
        
       		// Expected: 401 (auth check happens before resolution)

     

       248
       248
        
       		// In a real scenario with auth, invalid handle would return 404

     
···

       299
       299
        
       		blockHandler.HandleUnblock(w, req)

     

       300
       300
        
       

     

       301
       301
        
       		resp := w.Result()

     

       302
       302
       -
       		defer resp.Body.Close()

     

       302
       302
       +
       		defer func() { _ = resp.Body.Close() }()

     

       303
       303
        
       

     

       304
       304
        
       		// Should NOT be 404 (handle resolution should work)

     

       305
       305
        
       		if resp.StatusCode == http.StatusNotFound {

     
···

       309
       309
        
       		// Expected: 401 (no auth context)

     

       310
       310
        
       		if resp.StatusCode != http.StatusUnauthorized {

     

       311
       311
        
       			var errorResp map[string]interface{}

     

       312
       312
       -
       			json.NewDecoder(resp.Body).Decode(&errorResp)

     

       312
       312
       +
       			_ = json.NewDecoder(resp.Body).Decode(&errorResp)

     

       313
       313
        
       			t.Logf("Response: status=%d, body=%+v", resp.StatusCode, errorResp)

     

       314
       314
        
       		}

     

       315
       315
        
       	})

     
···

       328
       328
        
       		blockHandler.HandleUnblock(w, req)

     

       329
       329
        
       

     

       330
       330
        
       		resp := w.Result()

     

       331
       331
       -
       		defer resp.Body.Close()

     

       331
       331
       +
       		defer func() { _ = resp.Body.Close() }()

     

       332
       332
        
       

     

       333
       333
        
       		// Expected: 401 (auth check happens before resolution)

     

       334
       334
        
       		if resp.StatusCode != http.StatusUnauthorized && resp.StatusCode != http.StatusNotFound {

+3 -4

tests/integration/comment_consumer_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/jetstream"

     

       5
       5
       +
       	"Coves/internal/core/comments"

     

       6
       6
       +
       	"Coves/internal/db/postgres"

     

       4
       7
        
       	"context"

     

       5
       8
        
       	"fmt"

     

       6
       9
        
       	"testing"

     

       7
       10
        
       	"time"

     

       8
       8
       -
       

     

       9
       9
       -
       	"Coves/internal/atproto/jetstream"

     

       10
       10
       -
       	"Coves/internal/core/comments"

     

       11
       11
       -
       	"Coves/internal/db/postgres"

     

       12
       11
        
       )

     

       13
       12
        
       

     

       14
       13
        
       func TestCommentConsumer_CreateComment(t *testing.T) {

+3 -4

tests/integration/comment_query_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/jetstream"

     

       5
       5
       +
       	"Coves/internal/core/comments"

     

       6
       6
       +
       	"Coves/internal/db/postgres"

     

       4
       7
        
       	"context"

     

       5
       8
        
       	"database/sql"

     

       6
       9
        
       	"encoding/json"

     
···

       11
       14
        
       	"testing"

     

       12
       15
        
       	"time"

     

       13
       16
        
       

     

       14
       14
       -
       	"Coves/internal/atproto/jetstream"

     

       15
       15
       -
       	"Coves/internal/core/comments"

     

       16
       16
       -
       	"Coves/internal/db/postgres"

     

       17
       17
       -
       

     

       18
       17
        
       	"github.com/stretchr/testify/assert"

     

       19
       18
        
       	"github.com/stretchr/testify/require"

     

       20
       19
        
       )

+4 -5

tests/integration/comment_vote_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       -
       	"context"

     

       5
       5
       -
       	"fmt"

     

       6
       6
       -
       	"testing"

     

       7
       7
       -
       	"time"

     

       8
       8
       -
       

     

       9
       4
        
       	"Coves/internal/atproto/jetstream"

     

       10
       5
        
       	"Coves/internal/core/comments"

     

       11
       6
        
       	"Coves/internal/core/users"

     

       12
       7
        
       	"Coves/internal/db/postgres"

     

       8
       8
       +
       	"context"

     

       9
       9
       +
       	"fmt"

     

       10
       10
       +
       	"testing"

     

       11
       11
       +
       	"time"

     

       13
       12
        
       )

     

       14
       13
        
       

     

       15
       14
        
       // TestCommentVote_CreateAndUpdate tests voting on comments and vote count updates

+13 -14

tests/integration/community_e2e_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/middleware"

     

       5
       5
       +
       	"Coves/internal/api/routes"

     

       6
       6
       +
       	"Coves/internal/atproto/identity"

     

       7
       7
       +
       	"Coves/internal/atproto/jetstream"

     

       8
       8
       +
       	"Coves/internal/atproto/utils"

     

       9
       9
       +
       	"Coves/internal/core/communities"

     

       10
       10
       +
       	"Coves/internal/core/users"

     

       11
       11
       +
       	"Coves/internal/db/postgres"

     

       4
       12
        
       	"bytes"

     

       5
       13
        
       	"context"

     

       6
       14
        
       	"database/sql"

     
···

       15
       23
        
       	"testing"

     

       16
       24
        
       	"time"

     

       17
       25
        
       

     

       18
       18
       -
       	"Coves/internal/api/middleware"

     

       19
       19
       -
       	"Coves/internal/api/routes"

     

       20
       20
       -
       	"Coves/internal/atproto/identity"

     

       21
       21
       -
       	"Coves/internal/atproto/jetstream"

     

       22
       22
       -
       	"Coves/internal/atproto/utils"

     

       23
       23
       -
       	"Coves/internal/core/communities"

     

       24
       24
       -
       	"Coves/internal/core/users"

     

       25
       25
       -
       	"Coves/internal/db/postgres"

     

       26
       26
       -
       

     

       27
       26
        
       	"github.com/go-chi/chi/v5"

     

       28
       27
        
       	"github.com/gorilla/websocket"

     

       29
       28
        
       	_ "github.com/lib/pq"

     
···

       535
       534
        
       			}

     

       536
       535
        
       

     

       537
       536
        
       			var listResp struct {

     

       538
       538
       -
       				Communities []communities.Community `json:"communities"`

     

       539
       537
        
       				Cursor      string                  `json:"cursor"`

     

       538
       538
       +
       				Communities []communities.Community `json:"communities"`

     

       540
       539
        
       			}

     

       541
       540
        
       

     

       542
       541
        
       			if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {

     
···

       564
       563
        
       			}

     

       565
       564
        
       

     

       566
       565
        
       			var listResp struct {

     

       567
       567
       -
       				Communities []communities.Community `json:"communities"`

     

       568
       566
        
       				Cursor      string                  `json:"cursor"`

     

       567
       567
       +
       				Communities []communities.Community `json:"communities"`

     

       569
       568
        
       			}

     

       570
       569
        
       			if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {

     

       571
       570
        
       				t.Fatalf("Failed to decode response: %v", err)

     
···

       620
       619
        
       			}

     

       621
       620
        
       

     

       622
       621
        
       			var listResp struct {

     

       623
       623
       -
       				Communities []communities.Community `json:"communities"`

     

       624
       622
        
       				Cursor      string                  `json:"cursor"`

     

       623
       623
       +
       				Communities []communities.Community `json:"communities"`

     

       625
       624
        
       			}

     

       626
       625
        
       			if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {

     

       627
       626
        
       				t.Fatalf("Failed to decode response: %v", err)

     
···

       670
       669
        
       			}

     

       671
       670
        
       

     

       672
       671
        
       			var listResp struct {

     

       673
       673
       -
       				Communities []communities.Community `json:"communities"`

     

       674
       672
        
       				Cursor      string                  `json:"cursor"`

     

       673
       673
       +
       				Communities []communities.Community `json:"communities"`

     

       675
       674
        
       			}

     

       676
       675
        
       			if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {

     

       677
       676
        
       				t.Fatalf("Failed to decode response: %v", err)

     
···

       720
       719
        
       			}

     

       721
       720
        
       

     

       722
       721
        
       			var listResp struct {

     

       723
       723
       -
       				Communities []communities.Community `json:"communities"`

     

       724
       722
        
       				Cursor      string                  `json:"cursor"`

     

       723
       723
       +
       				Communities []communities.Community `json:"communities"`

     

       725
       724
        
       			}

     

       726
       725
        
       			if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {

     

       727
       726
        
       				t.Fatalf("Failed to decode response: %v", err)

+4 -5

tests/integration/community_hostedby_security_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/jetstream"

     

       5
       5
       +
       	"Coves/internal/db/postgres"

     

       4
       6
        
       	"context"

     

       5
       7
        
       	"fmt"

     

       6
       8
        
       	"net/http"

     
···

       8
       10
        
       	"strings"

     

       9
       11
        
       	"testing"

     

       10
       12
        
       	"time"

     

       11
       11
       -
       

     

       12
       12
       -
       	"Coves/internal/atproto/jetstream"

     

       13
       13
       -
       	"Coves/internal/db/postgres"

     

       14
       13
        
       )

     

       15
       14
        
       

     

       16
       15
        
       // TestHostedByVerification_DomainMatching tests that hostedBy domain must match handle domain

     
···

       257
       256
        
       				// Return a DID document with matching alsoKnownAs

     

       258
       257
        
       				w.Header().Set("Content-Type", "application/json")

     

       259
       258
        
       				w.WriteHeader(http.StatusOK)

     

       260
       260
       -
       				fmt.Fprintf(w, `{

     

       259
       259
       +
       				_, _ = fmt.Fprintf(w, `{

     

       261
       260
        
       					"id": "did:web:example.com",

     

       262
       261
        
       					"alsoKnownAs": ["at://example.com"],

     

       263
       262
        
       					"verificationMethod": [],

     
···

       332
       331
        
       				// Return a DID document WITHOUT alsoKnownAs field

     

       333
       332
        
       				w.Header().Set("Content-Type", "application/json")

     

       334
       333
        
       				w.WriteHeader(http.StatusOK)

     

       335
       335
       -
       				fmt.Fprintf(w, `{

     

       334
       334
       +
       				_, _ = fmt.Fprintf(w, `{

     

       336
       335
        
       					"id": "did:web:example.com",

     

       337
       336
        
       					"verificationMethod": [],

     

       338
       337
        
       					"service": []

+2 -3

tests/integration/community_repo_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/core/communities"

     

       5
       5
       +
       	"Coves/internal/db/postgres"

     

       4
       6
        
       	"context"

     

       5
       7
        
       	"fmt"

     

       6
       8
        
       	"testing"

     

       7
       9
        
       	"time"

     

       8
       8
       -
       

     

       9
       9
       -
       	"Coves/internal/core/communities"

     

       10
       10
       -
       	"Coves/internal/db/postgres"

     

       11
       10
        
       )

     

       12
       11
        
       

     

       13
       12
        
       func TestCommunityRepository_Create(t *testing.T) {

+6 -7

tests/integration/concurrent_scenarios_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       -
       	"context"

     

       5
       5
       -
       	"fmt"

     

       6
       6
       -
       	"sync"

     

       7
       7
       -
       	"testing"

     

       8
       8
       -
       	"time"

     

       9
       9
       -
       

     

       10
       4
        
       	"Coves/internal/atproto/jetstream"

     

       11
       5
        
       	"Coves/internal/core/comments"

     

       12
       6
        
       	"Coves/internal/core/communities"

     

       13
       7
        
       	"Coves/internal/core/users"

     

       14
       8
        
       	"Coves/internal/db/postgres"

     

       9
       9
       +
       	"context"

     

       10
       10
       +
       	"fmt"

     

       11
       11
       +
       	"sync"

     

       12
       12
       +
       	"testing"

     

       13
       13
       +
       	"time"

     

       15
       14
        
       )

     

       16
       15
        
       

     

       17
       16
        
       // TestConcurrentVoting_MultipleUsersOnSamePost tests race conditions when multiple users

     
···

       611
       610
        
       		wg.Add(numAttempts)

     

       612
       611
        
       

     

       613
       612
        
       		type result struct {

     

       614
       614
       -
       			success bool

     

       615
       613
        
       			err     error

     

       614
       614
       +
       			success bool

     

       616
       615
        
       		}

     

       617
       616
        
       		results := make(chan result, numAttempts)

     

       618
       617

+3 -4

tests/integration/jwt_verification_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/middleware"

     

       5
       5
       +
       	"Coves/internal/atproto/auth"

     

       4
       6
        
       	"fmt"

     

       5
       7
        
       	"net/http"

     

       6
       8
        
       	"net/http/httptest"

     
···

       8
       10
        
       	"strings"

     

       9
       11
        
       	"testing"

     

       10
       12
        
       	"time"

     

       11
       11
       -
       

     

       12
       12
       -
       	"Coves/internal/api/middleware"

     

       13
       13
       -
       	"Coves/internal/atproto/auth"

     

       14
       13
        
       )

     

       15
       14
        
       

     

       16
       15
        
       // TestJWTSignatureVerification tests end-to-end JWT signature verification

     
···

       46
       45
        
       	// Check if JWKS is available (production PDS) or symmetric secret (dev PDS)

     

       47
       46
        
       	jwksResp, _ := http.Get(pdsURL + "/oauth/jwks")

     

       48
       47
        
       	if jwksResp != nil {

     

       49
       49
       -
       		defer jwksResp.Body.Close()

     

       48
       48
       +
       		defer func() { _ = jwksResp.Body.Close() }()

     

       50
       49
        
       	}

     

       51
       50
        
       

     

       52
       51
        
       	t.Run("JWT parsing and middleware integration", func(t *testing.T) {

+3 -4

tests/integration/post_consumer_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/jetstream"

     

       5
       5
       +
       	"Coves/internal/core/users"

     

       6
       6
       +
       	"Coves/internal/db/postgres"

     

       4
       7
        
       	"context"

     

       5
       8
        
       	"fmt"

     

       6
       9
        
       	"testing"

     

       7
       10
        
       	"time"

     

       8
       8
       -
       

     

       9
       9
       -
       	"Coves/internal/atproto/jetstream"

     

       10
       10
       -
       	"Coves/internal/core/users"

     

       11
       11
       -
       	"Coves/internal/db/postgres"

     

       12
       11
        
       )

     

       13
       12
        
       

     

       14
       13
        
       // TestPostConsumer_CommentCountReconciliation tests that post comment_count

+3 -4

tests/integration/timeline_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/handlers/timeline"

     

       5
       5
       +
       	"Coves/internal/api/middleware"

     

       6
       6
       +
       	"Coves/internal/db/postgres"

     

       4
       7
        
       	"context"

     

       5
       8
        
       	"encoding/json"

     

       6
       9
        
       	"fmt"

     
···

       9
       12
        
       	"testing"

     

       10
       13
        
       	"time"

     

       11
       14
        
       

     

       12
       12
       -
       	"Coves/internal/api/handlers/timeline"

     

       13
       13
       -
       	"Coves/internal/api/middleware"

     

       14
       14
       -
       	"Coves/internal/db/postgres"

     

       15
       15
       -
       

     

       16
       15
        
       	timelineCore "Coves/internal/core/timeline"

     

       17
       16
        
       

     

       18
       17
        
       	"github.com/stretchr/testify/assert"

+11 -11

tests/integration/user_journey_e2e_test.go

···

       1
       1
        
       package integration

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/api/middleware"

     

       5
       5
       +
       	"Coves/internal/api/routes"

     

       6
       6
       +
       	"Coves/internal/atproto/identity"

     

       7
       7
       +
       	"Coves/internal/atproto/jetstream"

     

       8
       8
       +
       	"Coves/internal/core/communities"

     

       9
       9
       +
       	"Coves/internal/core/posts"

     

       10
       10
       +
       	"Coves/internal/core/users"

     

       11
       11
       +
       	"Coves/internal/db/postgres"

     

       4
       12
        
       	"bytes"

     

       5
       13
        
       	"context"

     

       6
       14
        
       	"database/sql"

     
···

       14
       22
        
       	"testing"

     

       15
       23
        
       	"time"

     

       16
       24
        
       

     

       17
       17
       -
       	"Coves/internal/api/middleware"

     

       18
       18
       -
       	"Coves/internal/api/routes"

     

       19
       19
       -
       	"Coves/internal/atproto/identity"

     

       20
       20
       -
       	"Coves/internal/atproto/jetstream"

     

       21
       21
       -
       	"Coves/internal/core/communities"

     

       22
       22
       -
       	"Coves/internal/core/posts"

     

       23
       25
        
       	timelineCore "Coves/internal/core/timeline"

     

       24
       24
       -
       	"Coves/internal/core/users"

     

       25
       25
       -
       	"Coves/internal/db/postgres"

     

       26
       26
        
       

     

       27
       27
        
       	"github.com/go-chi/chi/v5"

     

       28
       28
        
       	"github.com/gorilla/websocket"

     
···

       234
       234
        
       

     

       235
       235
        
       		resp, err := http.DefaultClient.Do(req)

     

       236
       236
        
       		require.NoError(t, err)

     

       237
       237
       -
       		defer resp.Body.Close()

     

       237
       237
       +
       		defer func() { _ = resp.Body.Close() }()

     

       238
       238
        
       

     

       239
       239
        
       		require.Equal(t, http.StatusOK, resp.StatusCode, "Community creation should succeed")

     

       240
       240
        
       

     
···

       318
       318
        
       

     

       319
       319
        
       		resp, err := http.DefaultClient.Do(req)

     

       320
       320
        
       		require.NoError(t, err)

     

       321
       321
       -
       		defer resp.Body.Close()

     

       321
       321
       +
       		defer func() { _ = resp.Body.Close() }()

     

       322
       322
        
       

     

       323
       323
        
       		require.Equal(t, http.StatusOK, resp.StatusCode, "Post creation should succeed")

     

       324
       324
        
       

     
···

       425
       425
        
       

     

       426
       426
        
       		resp, err := http.DefaultClient.Do(req)

     

       427
       427
        
       		require.NoError(t, err)

     

       428
       428
       -
       		defer resp.Body.Close()

     

       428
       428
       +
       		defer func() { _ = resp.Body.Close() }()

     

       429
       429
        
       

     

       430
       430
        
       		require.Equal(t, http.StatusOK, resp.StatusCode, "Subscription should succeed")

     

       431
       431

+23

static/.well-known/did.json

···

       1
       1
       +
       {

     

       2
       2
       +
         "@context": [

     

       3
       3
       +
           "https://www.w3.org/ns/did/v1",

     

       4
       4
       +
           "https://w3id.org/security/multikey/v1"

     

       5
       5
       +
         ],

     

       6
       6
       +
         "id": "did:web:coves.social",

     

       7
       7
       +
         "alsoKnownAs": ["at://coves.social"],

     

       8
       8
       +
         "verificationMethod": [

     

       9
       9
       +
           {

     

       10
       10
       +
             "id": "did:web:coves.social#atproto",

     

       11
       11
       +
             "type": "Multikey",

     

       12
       12
       +
             "controller": "did:web:coves.social",

     

       13
       13
       +
             "publicKeyMultibase": "zQ3shu1T3Y3MYoC1n7fCqkZqyrk8FiY3PV3BYM2JwyqcXFY6s"

     

       14
       14
       +
           }

     

       15
       15
       +
         ],

     

       16
       16
       +
         "service": [

     

       17
       17
       +
           {

     

       18
       18
       +
             "id": "#atproto_pds",

     

       19
       19
       +
             "type": "AtprotoPersonalDataServer",

     

       20
       20
       +
             "serviceEndpoint": "https://pds.coves.me"

     

       21
       21
       +
           }

     

       22
       22
       +
         ]

     

       23
       23
       +
       }

+1 -1

docs/E2E_TESTING.md

···

       93
       93
        
       

     

       94
       94
        
       Query via API:

     

       95
       95
        
       ```bash

     

       96
       96
       -
       curl "http://localhost:8081/xrpc/social.coves.actor.getProfile?actor=alice.local.coves.dev"

     

       96
       96
       +
       curl "http://localhost:8081/xrpc/social.coves.actor.getprofile?actor=alice.local.coves.dev"

     

       97
       97
        
       ```

     

       98
       98
        
       

     

       99
       99
        
       Expected response:

+3 -3

internal/api/routes/user.go

···

       28
       28
        
       func RegisterUserRoutes(r chi.Router, service users.UserService) {

     

       29
       29
        
       	h := NewUserHandler(service)

     

       30
       30
        
       

     

       31
       31
       -
       	// social.coves.actor.getProfile - query endpoint

     

       32
       32
       -
       	r.Get("/xrpc/social.coves.actor.getProfile", h.GetProfile)

     

       31
       31
       +
       	// social.coves.actor.getprofile - query endpoint

     

       32
       32
       +
       	r.Get("/xrpc/social.coves.actor.getprofile", h.GetProfile)

     

       33
       33
        
       

     

       34
       34
        
       	// social.coves.actor.signup - procedure endpoint

     

       35
       35
        
       	r.Post("/xrpc/social.coves.actor.signup", h.Signup)

     

       36
       36
        
       }

     

       37
       37
        
       

     

       38
       38
       -
       // GetProfile handles social.coves.actor.getProfile

     

       38
       38
       +
       // GetProfile handles social.coves.actor.getprofile

     

       39
       39
        
       // Query endpoint that retrieves a user profile by DID or handle

     

       40
       40
        
       func (h *UserHandler) GetProfile(w http.ResponseWriter, r *http.Request) {

     

       41
       41
        
       	ctx := r.Context()

+4 -4

tests/integration/user_test.go

···

       189
       189
        
       

     

       190
       190
        
       	// Test 1: Get profile by DID

     

       191
       191
        
       	t.Run("Get Profile By DID", func(t *testing.T) {

     

       192
       192
       -
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getProfile?actor=did:plc:endpoint123", nil)

     

       192
       192
       +
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getprofile?actor=did:plc:endpoint123", nil)

     

       193
       193
        
       		w := httptest.NewRecorder()

     

       194
       194
        
       		r.ServeHTTP(w, req)

     

       195
       195
        
       

     
···

       210
       210
        
       

     

       211
       211
        
       	// Test 2: Get profile by handle

     

       212
       212
        
       	t.Run("Get Profile By Handle", func(t *testing.T) {

     

       213
       213
       -
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getProfile?actor=bob.test", nil)

     

       213
       213
       +
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getprofile?actor=bob.test", nil)

     

       214
       214
        
       		w := httptest.NewRecorder()

     

       215
       215
        
       		r.ServeHTTP(w, req)

     

       216
       216
        
       

     
···

       232
       232
        
       

     

       233
       233
        
       	// Test 3: Missing actor parameter

     

       234
       234
        
       	t.Run("Missing Actor Parameter", func(t *testing.T) {

     

       235
       235
       -
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getProfile", nil)

     

       235
       235
       +
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getprofile", nil)

     

       236
       236
        
       		w := httptest.NewRecorder()

     

       237
       237
        
       		r.ServeHTTP(w, req)

     

       238
       238
        
       

     
···

       243
       243
        
       

     

       244
       244
        
       	// Test 4: User not found

     

       245
       245
        
       	t.Run("User Not Found", func(t *testing.T) {

     

       246
       246
       -
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getProfile?actor=nonexistent.test", nil)

     

       246
       246
       +
       		req := httptest.NewRequest("GET", "/xrpc/social.coves.actor.getprofile?actor=nonexistent.test", nil)

     

       247
       247
        
       		w := httptest.NewRecorder()

     

       248
       248
        
       		r.ServeHTTP(w, req)

     

       249
       249

+52

internal/atproto/auth/combined_key_fetcher.go

···

       1
       1
       +
       package auth

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"context"

     

       5
       5
       +
       	"fmt"

     

       6
       6
       +
       	"strings"

     

       7
       7
       +
       

     

       8
       8
       +
       	indigoIdentity "github.com/bluesky-social/indigo/atproto/identity"

     

       9
       9
       +
       )

     

       10
       10
       +
       

     

       11
       11
       +
       // CombinedKeyFetcher handles JWT public key fetching for both:

     

       12
       12
       +
       // - DID issuers (did:plc:, did:web:) → resolves via DID document

     

       13
       13
       +
       // - URL issuers (https://) → fetches via JWKS endpoint (legacy/fallback)

     

       14
       14
       +
       //

     

       15
       15
       +
       // For atproto service authentication, the issuer is typically the user's DID,

     

       16
       16
       +
       // and the signing key is published in their DID document.

     

       17
       17
       +
       type CombinedKeyFetcher struct {

     

       18
       18
       +
       	didFetcher  *DIDKeyFetcher

     

       19
       19
       +
       	jwksFetcher JWKSFetcher

     

       20
       20
       +
       }

     

       21
       21
       +
       

     

       22
       22
       +
       // NewCombinedKeyFetcher creates a key fetcher that supports both DID and URL issuers.

     

       23
       23
       +
       // Parameters:

     

       24
       24
       +
       //   - directory: Indigo's identity directory for DID resolution

     

       25
       25
       +
       //   - jwksFetcher: fallback JWKS fetcher for URL issuers (can be nil if not needed)

     

       26
       26
       +
       func NewCombinedKeyFetcher(directory indigoIdentity.Directory, jwksFetcher JWKSFetcher) *CombinedKeyFetcher {

     

       27
       27
       +
       	return &CombinedKeyFetcher{

     

       28
       28
       +
       		didFetcher:  NewDIDKeyFetcher(directory),

     

       29
       29
       +
       		jwksFetcher: jwksFetcher,

     

       30
       30
       +
       	}

     

       31
       31
       +
       }

     

       32
       32
       +
       

     

       33
       33
       +
       // FetchPublicKey fetches the public key for verifying a JWT.

     

       34
       34
       +
       // Routes to the appropriate fetcher based on issuer format:

     

       35
       35
       +
       // - DID (did:plc:, did:web:) → DIDKeyFetcher

     

       36
       36
       +
       // - URL (https://) → JWKSFetcher

     

       37
       37
       +
       func (f *CombinedKeyFetcher) FetchPublicKey(ctx context.Context, issuer, token string) (interface{}, error) {

     

       38
       38
       +
       	// Check if issuer is a DID

     

       39
       39
       +
       	if strings.HasPrefix(issuer, "did:") {

     

       40
       40
       +
       		return f.didFetcher.FetchPublicKey(ctx, issuer, token)

     

       41
       41
       +
       	}

     

       42
       42
       +
       

     

       43
       43
       +
       	// Check if issuer is a URL (https:// or http:// in dev)

     

       44
       44
       +
       	if strings.HasPrefix(issuer, "https://") || strings.HasPrefix(issuer, "http://") {

     

       45
       45
       +
       		if f.jwksFetcher == nil {

     

       46
       46
       +
       			return nil, fmt.Errorf("URL issuer %s requires JWKS fetcher, but none configured", issuer)

     

       47
       47
       +
       		}

     

       48
       48
       +
       		return f.jwksFetcher.FetchPublicKey(ctx, issuer, token)

     

       49
       49
       +
       	}

     

       50
       50
       +
       

     

       51
       51
       +
       	return nil, fmt.Errorf("unsupported issuer format: %s (expected DID or URL)", issuer)

     

       52
       52
       +
       }

+116

internal/atproto/auth/did_key_fetcher.go

···

       1
       1
       +
       package auth

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"context"

     

       5
       5
       +
       	"crypto/ecdsa"

     

       6
       6
       +
       	"crypto/elliptic"

     

       7
       7
       +
       	"encoding/base64"

     

       8
       8
       +
       	"fmt"

     

       9
       9
       +
       	"math/big"

     

       10
       10
       +
       	"strings"

     

       11
       11
       +
       

     

       12
       12
       +
       	"github.com/bluesky-social/indigo/atproto/atcrypto"

     

       13
       13
       +
       	indigoIdentity "github.com/bluesky-social/indigo/atproto/identity"

     

       14
       14
       +
       	"github.com/bluesky-social/indigo/atproto/syntax"

     

       15
       15
       +
       )

     

       16
       16
       +
       

     

       17
       17
       +
       // DIDKeyFetcher fetches public keys from DID documents for JWT verification.

     

       18
       18
       +
       // This is the primary method for atproto service authentication, where:

     

       19
       19
       +
       // - The JWT issuer is the user's DID (e.g., did:plc:abc123)

     

       20
       20
       +
       // - The signing key is published in the user's DID document

     

       21
       21
       +
       // - Verification happens by resolving the DID and checking the signature

     

       22
       22
       +
       type DIDKeyFetcher struct {

     

       23
       23
       +
       	directory indigoIdentity.Directory

     

       24
       24
       +
       }

     

       25
       25
       +
       

     

       26
       26
       +
       // NewDIDKeyFetcher creates a new DID-based key fetcher.

     

       27
       27
       +
       func NewDIDKeyFetcher(directory indigoIdentity.Directory) *DIDKeyFetcher {

     

       28
       28
       +
       	return &DIDKeyFetcher{

     

       29
       29
       +
       		directory: directory,

     

       30
       30
       +
       	}

     

       31
       31
       +
       }

     

       32
       32
       +
       

     

       33
       33
       +
       // FetchPublicKey fetches the public key for verifying a JWT from the issuer's DID document.

     

       34
       34
       +
       // For DID issuers (did:plc: or did:web:), resolves the DID and extracts the signing key.

     

       35
       35
       +
       // Returns an *ecdsa.PublicKey suitable for use with jwt-go.

     

       36
       36
       +
       func (f *DIDKeyFetcher) FetchPublicKey(ctx context.Context, issuer, token string) (interface{}, error) {

     

       37
       37
       +
       	// Only handle DID issuers

     

       38
       38
       +
       	if !strings.HasPrefix(issuer, "did:") {

     

       39
       39
       +
       		return nil, fmt.Errorf("DIDKeyFetcher only handles DID issuers, got: %s", issuer)

     

       40
       40
       +
       	}

     

       41
       41
       +
       

     

       42
       42
       +
       	// Parse the DID

     

       43
       43
       +
       	did, err := syntax.ParseDID(issuer)

     

       44
       44
       +
       	if err != nil {

     

       45
       45
       +
       		return nil, fmt.Errorf("invalid DID format: %w", err)

     

       46
       46
       +
       	}

     

       47
       47
       +
       

     

       48
       48
       +
       	// Resolve the DID to get the identity (includes public keys)

     

       49
       49
       +
       	ident, err := f.directory.LookupDID(ctx, did)

     

       50
       50
       +
       	if err != nil {

     

       51
       51
       +
       		return nil, fmt.Errorf("failed to resolve DID %s: %w", issuer, err)

     

       52
       52
       +
       	}

     

       53
       53
       +
       

     

       54
       54
       +
       	// Get the atproto signing key from the DID document

     

       55
       55
       +
       	pubKey, err := ident.PublicKey()

     

       56
       56
       +
       	if err != nil {

     

       57
       57
       +
       		return nil, fmt.Errorf("failed to get public key from DID document: %w", err)

     

       58
       58
       +
       	}

     

       59
       59
       +
       

     

       60
       60
       +
       	// Convert to JWK format to extract coordinates

     

       61
       61
       +
       	jwk, err := pubKey.JWK()

     

       62
       62
       +
       	if err != nil {

     

       63
       63
       +
       		return nil, fmt.Errorf("failed to convert public key to JWK: %w", err)

     

       64
       64
       +
       	}

     

       65
       65
       +
       

     

       66
       66
       +
       	// Convert atcrypto JWK to Go ecdsa.PublicKey

     

       67
       67
       +
       	return atcryptoJWKToECDSA(jwk)

     

       68
       68
       +
       }

     

       69
       69
       +
       

     

       70
       70
       +
       // atcryptoJWKToECDSA converts an atcrypto.JWK to a Go ecdsa.PublicKey

     

       71
       71
       +
       func atcryptoJWKToECDSA(jwk *atcrypto.JWK) (*ecdsa.PublicKey, error) {

     

       72
       72
       +
       	if jwk.KeyType != "EC" {

     

       73
       73
       +
       		return nil, fmt.Errorf("unsupported JWK key type: %s (expected EC)", jwk.KeyType)

     

       74
       74
       +
       	}

     

       75
       75
       +
       

     

       76
       76
       +
       	// Decode X and Y coordinates (base64url, no padding)

     

       77
       77
       +
       	xBytes, err := base64.RawURLEncoding.DecodeString(jwk.X)

     

       78
       78
       +
       	if err != nil {

     

       79
       79
       +
       		return nil, fmt.Errorf("invalid JWK X coordinate encoding: %w", err)

     

       80
       80
       +
       	}

     

       81
       81
       +
       	yBytes, err := base64.RawURLEncoding.DecodeString(jwk.Y)

     

       82
       82
       +
       	if err != nil {

     

       83
       83
       +
       		return nil, fmt.Errorf("invalid JWK Y coordinate encoding: %w", err)

     

       84
       84
       +
       	}

     

       85
       85
       +
       

     

       86
       86
       +
       	var ecCurve elliptic.Curve

     

       87
       87
       +
       	switch jwk.Curve {

     

       88
       88
       +
       	case "P-256":

     

       89
       89
       +
       		ecCurve = elliptic.P256()

     

       90
       90
       +
       	case "P-384":

     

       91
       91
       +
       		ecCurve = elliptic.P384()

     

       92
       92
       +
       	case "P-521":

     

       93
       93
       +
       		ecCurve = elliptic.P521()

     

       94
       94
       +
       	case "secp256k1":

     

       95
       95
       +
       		// secp256k1 (K-256) is used by some atproto implementations

     

       96
       96
       +
       		// Go's standard library doesn't include secp256k1, but we can still

     

       97
       97
       +
       		// construct the key - jwt-go may not support it directly

     

       98
       98
       +
       		return nil, fmt.Errorf("secp256k1 curve requires special handling for JWT verification")

     

       99
       99
       +
       	default:

     

       100
       100
       +
       		return nil, fmt.Errorf("unsupported JWK curve: %s", jwk.Curve)

     

       101
       101
       +
       	}

     

       102
       102
       +
       

     

       103
       103
       +
       	// Create the public key

     

       104
       104
       +
       	pubKey := &ecdsa.PublicKey{

     

       105
       105
       +
       		Curve: ecCurve,

     

       106
       106
       +
       		X:     new(big.Int).SetBytes(xBytes),

     

       107
       107
       +
       		Y:     new(big.Int).SetBytes(yBytes),

     

       108
       108
       +
       	}

     

       109
       109
       +
       

     

       110
       110
       +
       	// Validate point is on curve

     

       111
       111
       +
       	if !ecCurve.IsOnCurve(pubKey.X, pubKey.Y) {

     

       112
       112
       +
       		return nil, fmt.Errorf("invalid public key: point not on curve")

     

       113
       113
       +
       	}

     

       114
       114
       +
       

     

       115
       115
       +
       	return pubKey, nil

     

       116
       116
       +
       }

+24 -3

cmd/server/main.go

···

       36
       36
        
       	commentsAPI "Coves/internal/api/handlers/comments"

     

       37
       37
        
       

     

       38
       38
        
       	postgresRepo "Coves/internal/db/postgres"

     

       39
       39
       +
       

     

       40
       40
       +
       	indigoIdentity "github.com/bluesky-social/indigo/atproto/identity"

     

       39
       41
        
       )

     

       40
       42
        
       

     

       41
       43
        
       func main() {

     
···

       142
       144
        
       		log.Println("   Set AUTH_SKIP_VERIFY=false for production")

     

       143
       145
        
       	}

     

       144
       146
        
       

     

       145
       145
       -
       	jwksCacheTTL := 1 * time.Hour // Cache public keys for 1 hour

     

       147
       147
       +
       	// Initialize Indigo directory for DID resolution (used by auth)

     

       148
       148
       +
       	plcURL := os.Getenv("PLC_DIRECTORY_URL")

     

       149
       149
       +
       	if plcURL == "" {

     

       150
       150
       +
       		plcURL = "https://plc.directory"

     

       151
       151
       +
       	}

     

       152
       152
       +
       	indigoDir := &indigoIdentity.BaseDirectory{

     

       153
       153
       +
       		PLCURL:     plcURL,

     

       154
       154
       +
       		HTTPClient: http.Client{Timeout: 10 * time.Second},

     

       155
       155
       +
       	}

     

       156
       156
       +
       

     

       157
       157
       +
       	// Initialize JWT config early to cache HS256_ISSUERS and PDS_JWT_SECRET

     

       158
       158
       +
       	// This avoids reading env vars on every request

     

       159
       159
       +
       	auth.InitJWTConfig()

     

       160
       160
       +
       

     

       161
       161
       +
       	// Create combined key fetcher for both DID and URL issuers

     

       162
       162
       +
       	// - DID issuers (did:plc:, did:web:) → resolved via DID document keys (ES256)

     

       163
       163
       +
       	// - URL issuers → JWKS endpoint (fallback for legacy tokens)

     

       164
       164
       +
       	jwksCacheTTL := 1 * time.Hour

     

       146
       165
        
       	jwksFetcher := auth.NewCachedJWKSFetcher(jwksCacheTTL)

     

       147
       147
       -
       	authMiddleware := middleware.NewAtProtoAuthMiddleware(jwksFetcher, skipVerify)

     

       148
       148
       -
       	log.Println("✅ atProto auth middleware initialized")

     

       166
       166
       +
       	keyFetcher := auth.NewCombinedKeyFetcher(indigoDir, jwksFetcher)

     

       167
       167
       +
       

     

       168
       168
       +
       	authMiddleware := middleware.NewAtProtoAuthMiddleware(keyFetcher, skipVerify)

     

       169
       169
       +
       	log.Println("✅ atProto auth middleware initialized (DID + JWKS key resolution)")

     

       149
       170
        
       

     

       150
       171
        
       	// Initialize repositories and services

     

       151
       172
        
       	userRepo := postgresRepo.NewUserRepository(db)

.env.dev

···

       152
       152
        
       # When false, verifies JWT signature against issuer's JWKS

     

       153
       153
        
       AUTH_SKIP_VERIFY=true

     

       154
       154
        
       

     

       155
       155
       +
       # HS256 Issuers: PDSes allowed to use HS256 (shared secret) authentication

     

       156
       156
       +
       # Must share PDS_JWT_SECRET with Coves instance. External PDSes use ES256 via DID resolution.

     

       157
       157
       +
       # For local dev, allow the local PDS or turn AUTH_SKIP_VERIFY = true

     

       158
       158
       +
       HS256_ISSUERS=http://localhost:3001

     

       159
       159
       +
       

     

       155
       160
        
       # Logging

     

       156
       161
        
       LOG_LEVEL=debug

     

       157
       162
        
       LOG_ENABLED=true

+484

internal/atproto/auth/dpop.go

···

       1
       1
       +
       package auth

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"crypto/ecdsa"

     

       5
       5
       +
       	"crypto/elliptic"

     

       6
       6
       +
       	"crypto/sha256"

     

       7
       7
       +
       	"encoding/base64"

     

       8
       8
       +
       	"encoding/json"

     

       9
       9
       +
       	"fmt"

     

       10
       10
       +
       	"math/big"

     

       11
       11
       +
       	"strings"

     

       12
       12
       +
       	"sync"

     

       13
       13
       +
       	"time"

     

       14
       14
       +
       

     

       15
       15
       +
       	indigoCrypto "github.com/bluesky-social/indigo/atproto/atcrypto"

     

       16
       16
       +
       	"github.com/golang-jwt/jwt/v5"

     

       17
       17
       +
       )

     

       18
       18
       +
       

     

       19
       19
       +
       // NonceCache provides replay protection for DPoP proofs by tracking seen jti values.

     

       20
       20
       +
       // This prevents an attacker from reusing a captured DPoP proof within the validity window.

     

       21
       21
       +
       // Per RFC 9449 Section 11.1, servers SHOULD prevent replay attacks.

     

       22
       22
       +
       type NonceCache struct {

     

       23
       23
       +
       	seen    map[string]time.Time // jti -> expiration time

     

       24
       24
       +
       	stopCh  chan struct{}

     

       25
       25
       +
       	maxAge  time.Duration // How long to keep entries

     

       26
       26
       +
       	cleanup time.Duration // How often to clean up expired entries

     

       27
       27
       +
       	mu      sync.RWMutex

     

       28
       28
       +
       }

     

       29
       29
       +
       

     

       30
       30
       +
       // NewNonceCache creates a new nonce cache for DPoP replay protection.

     

       31
       31
       +
       // maxAge should match or exceed DPoPVerifier.MaxProofAge.

     

       32
       32
       +
       func NewNonceCache(maxAge time.Duration) *NonceCache {

     

       33
       33
       +
       	nc := &NonceCache{

     

       34
       34
       +
       		seen:    make(map[string]time.Time),

     

       35
       35
       +
       		maxAge:  maxAge,

     

       36
       36
       +
       		cleanup: maxAge / 2, // Clean up at half the max age

     

       37
       37
       +
       		stopCh:  make(chan struct{}),

     

       38
       38
       +
       	}

     

       39
       39
       +
       

     

       40
       40
       +
       	// Start background cleanup goroutine

     

       41
       41
       +
       	go nc.cleanupLoop()

     

       42
       42
       +
       

     

       43
       43
       +
       	return nc

     

       44
       44
       +
       }

     

       45
       45
       +
       

     

       46
       46
       +
       // CheckAndStore checks if a jti has been seen before and stores it if not.

     

       47
       47
       +
       // Returns true if the jti is fresh (not a replay), false if it's a replay.

     

       48
       48
       +
       func (nc *NonceCache) CheckAndStore(jti string) bool {

     

       49
       49
       +
       	nc.mu.Lock()

     

       50
       50
       +
       	defer nc.mu.Unlock()

     

       51
       51
       +
       

     

       52
       52
       +
       	now := time.Now()

     

       53
       53
       +
       	expiry := now.Add(nc.maxAge)

     

       54
       54
       +
       

     

       55
       55
       +
       	// Check if already seen

     

       56
       56
       +
       	if existingExpiry, seen := nc.seen[jti]; seen {

     

       57
       57
       +
       		// Still valid (not expired) - this is a replay

     

       58
       58
       +
       		if existingExpiry.After(now) {

     

       59
       59
       +
       			return false

     

       60
       60
       +
       		}

     

       61
       61
       +
       		// Expired entry - allow reuse and update expiry

     

       62
       62
       +
       	}

     

       63
       63
       +
       

     

       64
       64
       +
       	// Store the new jti

     

       65
       65
       +
       	nc.seen[jti] = expiry

     

       66
       66
       +
       	return true

     

       67
       67
       +
       }

     

       68
       68
       +
       

     

       69
       69
       +
       // cleanupLoop periodically removes expired entries from the cache

     

       70
       70
       +
       func (nc *NonceCache) cleanupLoop() {

     

       71
       71
       +
       	ticker := time.NewTicker(nc.cleanup)

     

       72
       72
       +
       	defer ticker.Stop()

     

       73
       73
       +
       

     

       74
       74
       +
       	for {

     

       75
       75
       +
       		select {

     

       76
       76
       +
       		case <-ticker.C:

     

       77
       77
       +
       			nc.cleanupExpired()

     

       78
       78
       +
       		case <-nc.stopCh:

     

       79
       79
       +
       			return

     

       80
       80
       +
       		}

     

       81
       81
       +
       	}

     

       82
       82
       +
       }

     

       83
       83
       +
       

     

       84
       84
       +
       // cleanupExpired removes expired entries from the cache

     

       85
       85
       +
       func (nc *NonceCache) cleanupExpired() {

     

       86
       86
       +
       	nc.mu.Lock()

     

       87
       87
       +
       	defer nc.mu.Unlock()

     

       88
       88
       +
       

     

       89
       89
       +
       	now := time.Now()

     

       90
       90
       +
       	for jti, expiry := range nc.seen {

     

       91
       91
       +
       		if expiry.Before(now) {

     

       92
       92
       +
       			delete(nc.seen, jti)

     

       93
       93
       +
       		}

     

       94
       94
       +
       	}

     

       95
       95
       +
       }

     

       96
       96
       +
       

     

       97
       97
       +
       // Stop stops the cleanup goroutine. Call this when done with the cache.

     

       98
       98
       +
       func (nc *NonceCache) Stop() {

     

       99
       99
       +
       	close(nc.stopCh)

     

       100
       100
       +
       }

     

       101
       101
       +
       

     

       102
       102
       +
       // Size returns the number of entries in the cache (for testing/monitoring)

     

       103
       103
       +
       func (nc *NonceCache) Size() int {

     

       104
       104
       +
       	nc.mu.RLock()

     

       105
       105
       +
       	defer nc.mu.RUnlock()

     

       106
       106
       +
       	return len(nc.seen)

     

       107
       107
       +
       }

     

       108
       108
       +
       

     

       109
       109
       +
       // DPoPClaims represents the claims in a DPoP proof JWT (RFC 9449)

     

       110
       110
       +
       type DPoPClaims struct {

     

       111
       111
       +
       	jwt.RegisteredClaims

     

       112
       112
       +
       

     

       113
       113
       +
       	// HTTP method of the request (e.g., "GET", "POST")

     

       114
       114
       +
       	HTTPMethod string `json:"htm"`

     

       115
       115
       +
       

     

       116
       116
       +
       	// HTTP URI of the request (without query and fragment parts)

     

       117
       117
       +
       	HTTPURI string `json:"htu"`

     

       118
       118
       +
       

     

       119
       119
       +
       	// Access token hash (optional, for token binding)

     

       120
       120
       +
       	AccessTokenHash string `json:"ath,omitempty"`

     

       121
       121
       +
       }

     

       122
       122
       +
       

     

       123
       123
       +
       // DPoPProof represents a parsed and verified DPoP proof

     

       124
       124
       +
       type DPoPProof struct {

     

       125
       125
       +
       	RawPublicJWK map[string]interface{}

     

       126
       126
       +
       	Claims       *DPoPClaims

     

       127
       127
       +
       	PublicKey    interface{} // *ecdsa.PublicKey or similar

     

       128
       128
       +
       	Thumbprint   string      // JWK thumbprint (base64url)

     

       129
       129
       +
       }

     

       130
       130
       +
       

     

       131
       131
       +
       // DPoPVerifier verifies DPoP proofs for OAuth token binding

     

       132
       132
       +
       type DPoPVerifier struct {

     

       133
       133
       +
       	// Optional: custom nonce validation function (for server-issued nonces)

     

       134
       134
       +
       	ValidateNonce func(nonce string) bool

     

       135
       135
       +
       

     

       136
       136
       +
       	// NonceCache for replay protection (optional but recommended)

     

       137
       137
       +
       	// If nil, jti replay protection is disabled

     

       138
       138
       +
       	NonceCache *NonceCache

     

       139
       139
       +
       

     

       140
       140
       +
       	// Maximum allowed clock skew for timestamp validation

     

       141
       141
       +
       	MaxClockSkew time.Duration

     

       142
       142
       +
       

     

       143
       143
       +
       	// Maximum age of DPoP proof (prevents replay with old proofs)

     

       144
       144
       +
       	MaxProofAge time.Duration

     

       145
       145
       +
       }

     

       146
       146
       +
       

     

       147
       147
       +
       // NewDPoPVerifier creates a DPoP verifier with sensible defaults including replay protection

     

       148
       148
       +
       func NewDPoPVerifier() *DPoPVerifier {

     

       149
       149
       +
       	maxProofAge := 5 * time.Minute

     

       150
       150
       +
       	return &DPoPVerifier{

     

       151
       151
       +
       		MaxClockSkew: 30 * time.Second,

     

       152
       152
       +
       		MaxProofAge:  maxProofAge,

     

       153
       153
       +
       		NonceCache:   NewNonceCache(maxProofAge),

     

       154
       154
       +
       	}

     

       155
       155
       +
       }

     

       156
       156
       +
       

     

       157
       157
       +
       // NewDPoPVerifierWithoutReplayProtection creates a DPoP verifier without replay protection.

     

       158
       158
       +
       // This should only be used in testing or when replay protection is handled externally.

     

       159
       159
       +
       func NewDPoPVerifierWithoutReplayProtection() *DPoPVerifier {

     

       160
       160
       +
       	return &DPoPVerifier{

     

       161
       161
       +
       		MaxClockSkew: 30 * time.Second,

     

       162
       162
       +
       		MaxProofAge:  5 * time.Minute,

     

       163
       163
       +
       		NonceCache:   nil, // No replay protection

     

       164
       164
       +
       	}

     

       165
       165
       +
       }

     

       166
       166
       +
       

     

       167
       167
       +
       // Stop stops background goroutines. Call this when shutting down.

     

       168
       168
       +
       func (v *DPoPVerifier) Stop() {

     

       169
       169
       +
       	if v.NonceCache != nil {

     

       170
       170
       +
       		v.NonceCache.Stop()

     

       171
       171
       +
       	}

     

       172
       172
       +
       }

     

       173
       173
       +
       

     

       174
       174
       +
       // VerifyDPoPProof verifies a DPoP proof JWT and returns the parsed proof

     

       175
       175
       +
       func (v *DPoPVerifier) VerifyDPoPProof(dpopProof, httpMethod, httpURI string) (*DPoPProof, error) {

     

       176
       176
       +
       	// Parse the DPoP JWT without verification first to extract the header

     

       177
       177
       +
       	parser := jwt.NewParser(jwt.WithoutClaimsValidation())

     

       178
       178
       +
       	token, _, err := parser.ParseUnverified(dpopProof, &DPoPClaims{})

     

       179
       179
       +
       	if err != nil {

     

       180
       180
       +
       		return nil, fmt.Errorf("failed to parse DPoP proof: %w", err)

     

       181
       181
       +
       	}

     

       182
       182
       +
       

     

       183
       183
       +
       	// Extract and validate the header

     

       184
       184
       +
       	header, ok := token.Header["typ"].(string)

     

       185
       185
       +
       	if !ok || header != "dpop+jwt" {

     

       186
       186
       +
       		return nil, fmt.Errorf("invalid DPoP proof: typ must be 'dpop+jwt', got '%s'", header)

     

       187
       187
       +
       	}

     

       188
       188
       +
       

     

       189
       189
       +
       	alg, ok := token.Header["alg"].(string)

     

       190
       190
       +
       	if !ok {

     

       191
       191
       +
       		return nil, fmt.Errorf("invalid DPoP proof: missing alg header")

     

       192
       192
       +
       	}

     

       193
       193
       +
       

     

       194
       194
       +
       	// Extract the JWK from the header

     

       195
       195
       +
       	jwkRaw, ok := token.Header["jwk"]

     

       196
       196
       +
       	if !ok {

     

       197
       197
       +
       		return nil, fmt.Errorf("invalid DPoP proof: missing jwk header")

     

       198
       198
       +
       	}

     

       199
       199
       +
       

     

       200
       200
       +
       	jwkMap, ok := jwkRaw.(map[string]interface{})

     

       201
       201
       +
       	if !ok {

     

       202
       202
       +
       		return nil, fmt.Errorf("invalid DPoP proof: jwk must be an object")

     

       203
       203
       +
       	}

     

       204
       204
       +
       

     

       205
       205
       +
       	// Parse the public key from JWK

     

       206
       206
       +
       	publicKey, err := parseJWKToPublicKey(jwkMap)

     

       207
       207
       +
       	if err != nil {

     

       208
       208
       +
       		return nil, fmt.Errorf("invalid DPoP proof JWK: %w", err)

     

       209
       209
       +
       	}

     

       210
       210
       +
       

     

       211
       211
       +
       	// Calculate the JWK thumbprint

     

       212
       212
       +
       	thumbprint, err := CalculateJWKThumbprint(jwkMap)

     

       213
       213
       +
       	if err != nil {

     

       214
       214
       +
       		return nil, fmt.Errorf("failed to calculate JWK thumbprint: %w", err)

     

       215
       215
       +
       	}

     

       216
       216
       +
       

     

       217
       217
       +
       	// Now verify the signature

     

       218
       218
       +
       	verifiedToken, err := jwt.ParseWithClaims(dpopProof, &DPoPClaims{}, func(token *jwt.Token) (interface{}, error) {

     

       219
       219
       +
       		// Verify the signing method matches what we expect

     

       220
       220
       +
       		switch alg {

     

       221
       221
       +
       		case "ES256":

     

       222
       222
       +
       			if _, ok := token.Method.(*jwt.SigningMethodECDSA); !ok {

     

       223
       223
       +
       				return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])

     

       224
       224
       +
       			}

     

       225
       225
       +
       		case "ES384", "ES512":

     

       226
       226
       +
       			if _, ok := token.Method.(*jwt.SigningMethodECDSA); !ok {

     

       227
       227
       +
       				return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])

     

       228
       228
       +
       			}

     

       229
       229
       +
       		case "RS256", "RS384", "RS512", "PS256", "PS384", "PS512":

     

       230
       230
       +
       			// RSA methods - we primarily support ES256 for atproto

     

       231
       231
       +
       			return nil, fmt.Errorf("RSA algorithms not yet supported for DPoP: %s", alg)

     

       232
       232
       +
       		default:

     

       233
       233
       +
       			return nil, fmt.Errorf("unsupported DPoP algorithm: %s", alg)

     

       234
       234
       +
       		}

     

       235
       235
       +
       		return publicKey, nil

     

       236
       236
       +
       	})

     

       237
       237
       +
       	if err != nil {

     

       238
       238
       +
       		return nil, fmt.Errorf("DPoP proof signature verification failed: %w", err)

     

       239
       239
       +
       	}

     

       240
       240
       +
       

     

       241
       241
       +
       	claims, ok := verifiedToken.Claims.(*DPoPClaims)

     

       242
       242
       +
       	if !ok {

     

       243
       243
       +
       		return nil, fmt.Errorf("invalid DPoP claims type")

     

       244
       244
       +
       	}

     

       245
       245
       +
       

     

       246
       246
       +
       	// Validate the claims

     

       247
       247
       +
       	if err := v.validateDPoPClaims(claims, httpMethod, httpURI); err != nil {

     

       248
       248
       +
       		return nil, err

     

       249
       249
       +
       	}

     

       250
       250
       +
       

     

       251
       251
       +
       	return &DPoPProof{

     

       252
       252
       +
       		Claims:       claims,

     

       253
       253
       +
       		PublicKey:    publicKey,

     

       254
       254
       +
       		Thumbprint:   thumbprint,

     

       255
       255
       +
       		RawPublicJWK: jwkMap,

     

       256
       256
       +
       	}, nil

     

       257
       257
       +
       }

     

       258
       258
       +
       

     

       259
       259
       +
       // validateDPoPClaims validates the DPoP proof claims

     

       260
       260
       +
       func (v *DPoPVerifier) validateDPoPClaims(claims *DPoPClaims, expectedMethod, expectedURI string) error {

     

       261
       261
       +
       	// Validate jti (unique identifier) is present

     

       262
       262
       +
       	if claims.ID == "" {

     

       263
       263
       +
       		return fmt.Errorf("DPoP proof missing jti claim")

     

       264
       264
       +
       	}

     

       265
       265
       +
       

     

       266
       266
       +
       	// Validate htm (HTTP method)

     

       267
       267
       +
       	if !strings.EqualFold(claims.HTTPMethod, expectedMethod) {

     

       268
       268
       +
       		return fmt.Errorf("DPoP proof htm mismatch: expected %s, got %s", expectedMethod, claims.HTTPMethod)

     

       269
       269
       +
       	}

     

       270
       270
       +
       

     

       271
       271
       +
       	// Validate htu (HTTP URI) - compare without query/fragment

     

       272
       272
       +
       	expectedURIBase := stripQueryFragment(expectedURI)

     

       273
       273
       +
       	claimURIBase := stripQueryFragment(claims.HTTPURI)

     

       274
       274
       +
       	if expectedURIBase != claimURIBase {

     

       275
       275
       +
       		return fmt.Errorf("DPoP proof htu mismatch: expected %s, got %s", expectedURIBase, claimURIBase)

     

       276
       276
       +
       	}

     

       277
       277
       +
       

     

       278
       278
       +
       	// Validate iat (issued at) is present and recent

     

       279
       279
       +
       	if claims.IssuedAt == nil {

     

       280
       280
       +
       		return fmt.Errorf("DPoP proof missing iat claim")

     

       281
       281
       +
       	}

     

       282
       282
       +
       

     

       283
       283
       +
       	now := time.Now()

     

       284
       284
       +
       	iat := claims.IssuedAt.Time

     

       285
       285
       +
       

     

       286
       286
       +
       	// Check clock skew (not too far in the future)

     

       287
       287
       +
       	if iat.After(now.Add(v.MaxClockSkew)) {

     

       288
       288
       +
       		return fmt.Errorf("DPoP proof iat is in the future")

     

       289
       289
       +
       	}

     

       290
       290
       +
       

     

       291
       291
       +
       	// Check proof age (not too old)

     

       292
       292
       +
       	if now.Sub(iat) > v.MaxProofAge {

     

       293
       293
       +
       		return fmt.Errorf("DPoP proof is too old (issued %v ago, max %v)", now.Sub(iat), v.MaxProofAge)

     

       294
       294
       +
       	}

     

       295
       295
       +
       

     

       296
       296
       +
       	// SECURITY: Check for replay attack using jti

     

       297
       297
       +
       	// Per RFC 9449 Section 11.1, servers SHOULD prevent replay attacks

     

       298
       298
       +
       	if v.NonceCache != nil {

     

       299
       299
       +
       		if !v.NonceCache.CheckAndStore(claims.ID) {

     

       300
       300
       +
       			return fmt.Errorf("DPoP proof replay detected: jti %s already used", claims.ID)

     

       301
       301
       +
       		}

     

       302
       302
       +
       	}

     

       303
       303
       +
       

     

       304
       304
       +
       	return nil

     

       305
       305
       +
       }

     

       306
       306
       +
       

     

       307
       307
       +
       // VerifyTokenBinding verifies that the DPoP proof binds to the access token

     

       308
       308
       +
       // by comparing the proof's thumbprint to the token's cnf.jkt claim

     

       309
       309
       +
       func (v *DPoPVerifier) VerifyTokenBinding(proof *DPoPProof, expectedThumbprint string) error {

     

       310
       310
       +
       	if proof.Thumbprint != expectedThumbprint {

     

       311
       311
       +
       		return fmt.Errorf("DPoP proof thumbprint mismatch: token expects %s, proof has %s",

     

       312
       312
       +
       			expectedThumbprint, proof.Thumbprint)

     

       313
       313
       +
       	}

     

       314
       314
       +
       	return nil

     

       315
       315
       +
       }

     

       316
       316
       +
       

     

       317
       317
       +
       // CalculateJWKThumbprint calculates the JWK thumbprint per RFC 7638

     

       318
       318
       +
       // The thumbprint is the base64url-encoded SHA-256 hash of the canonical JWK representation

     

       319
       319
       +
       func CalculateJWKThumbprint(jwk map[string]interface{}) (string, error) {

     

       320
       320
       +
       	kty, ok := jwk["kty"].(string)

     

       321
       321
       +
       	if !ok {

     

       322
       322
       +
       		return "", fmt.Errorf("JWK missing kty")

     

       323
       323
       +
       	}

     

       324
       324
       +
       

     

       325
       325
       +
       	// Build the canonical JWK representation based on key type

     

       326
       326
       +
       	// Per RFC 7638, only specific members are included, in lexicographic order

     

       327
       327
       +
       	var canonical map[string]string

     

       328
       328
       +
       

     

       329
       329
       +
       	switch kty {

     

       330
       330
       +
       	case "EC":

     

       331
       331
       +
       		crv, ok := jwk["crv"].(string)

     

       332
       332
       +
       		if !ok {

     

       333
       333
       +
       			return "", fmt.Errorf("EC JWK missing crv")

     

       334
       334
       +
       		}

     

       335
       335
       +
       		x, ok := jwk["x"].(string)

     

       336
       336
       +
       		if !ok {

     

       337
       337
       +
       			return "", fmt.Errorf("EC JWK missing x")

     

       338
       338
       +
       		}

     

       339
       339
       +
       		y, ok := jwk["y"].(string)

     

       340
       340
       +
       		if !ok {

     

       341
       341
       +
       			return "", fmt.Errorf("EC JWK missing y")

     

       342
       342
       +
       		}

     

       343
       343
       +
       		// Lexicographic order: crv, kty, x, y

     

       344
       344
       +
       		canonical = map[string]string{

     

       345
       345
       +
       			"crv": crv,

     

       346
       346
       +
       			"kty": kty,

     

       347
       347
       +
       			"x":   x,

     

       348
       348
       +
       			"y":   y,

     

       349
       349
       +
       		}

     

       350
       350
       +
       	case "RSA":

     

       351
       351
       +
       		e, ok := jwk["e"].(string)

     

       352
       352
       +
       		if !ok {

     

       353
       353
       +
       			return "", fmt.Errorf("RSA JWK missing e")

     

       354
       354
       +
       		}

     

       355
       355
       +
       		n, ok := jwk["n"].(string)

     

       356
       356
       +
       		if !ok {

     

       357
       357
       +
       			return "", fmt.Errorf("RSA JWK missing n")

     

       358
       358
       +
       		}

     

       359
       359
       +
       		// Lexicographic order: e, kty, n

     

       360
       360
       +
       		canonical = map[string]string{

     

       361
       361
       +
       			"e":   e,

     

       362
       362
       +
       			"kty": kty,

     

       363
       363
       +
       			"n":   n,

     

       364
       364
       +
       		}

     

       365
       365
       +
       	case "OKP":

     

       366
       366
       +
       		crv, ok := jwk["crv"].(string)

     

       367
       367
       +
       		if !ok {

     

       368
       368
       +
       			return "", fmt.Errorf("OKP JWK missing crv")

     

       369
       369
       +
       		}

     

       370
       370
       +
       		x, ok := jwk["x"].(string)

     

       371
       371
       +
       		if !ok {

     

       372
       372
       +
       			return "", fmt.Errorf("OKP JWK missing x")

     

       373
       373
       +
       		}

     

       374
       374
       +
       		// Lexicographic order: crv, kty, x

     

       375
       375
       +
       		canonical = map[string]string{

     

       376
       376
       +
       			"crv": crv,

     

       377
       377
       +
       			"kty": kty,

     

       378
       378
       +
       			"x":   x,

     

       379
       379
       +
       		}

     

       380
       380
       +
       	default:

     

       381
       381
       +
       		return "", fmt.Errorf("unsupported JWK key type: %s", kty)

     

       382
       382
       +
       	}

     

       383
       383
       +
       

     

       384
       384
       +
       	// Serialize to JSON (Go's json.Marshal produces lexicographically ordered keys for map[string]string)

     

       385
       385
       +
       	canonicalJSON, err := json.Marshal(canonical)

     

       386
       386
       +
       	if err != nil {

     

       387
       387
       +
       		return "", fmt.Errorf("failed to serialize canonical JWK: %w", err)

     

       388
       388
       +
       	}

     

       389
       389
       +
       

     

       390
       390
       +
       	// SHA-256 hash

     

       391
       391
       +
       	hash := sha256.Sum256(canonicalJSON)

     

       392
       392
       +
       

     

       393
       393
       +
       	// Base64url encode (no padding)

     

       394
       394
       +
       	thumbprint := base64.RawURLEncoding.EncodeToString(hash[:])

     

       395
       395
       +
       

     

       396
       396
       +
       	return thumbprint, nil

     

       397
       397
       +
       }

     

       398
       398
       +
       

     

       399
       399
       +
       // parseJWKToPublicKey parses a JWK map to a Go public key

     

       400
       400
       +
       func parseJWKToPublicKey(jwkMap map[string]interface{}) (interface{}, error) {

     

       401
       401
       +
       	// Convert map to JSON bytes for indigo's parser

     

       402
       402
       +
       	jwkBytes, err := json.Marshal(jwkMap)

     

       403
       403
       +
       	if err != nil {

     

       404
       404
       +
       		return nil, fmt.Errorf("failed to serialize JWK: %w", err)

     

       405
       405
       +
       	}

     

       406
       406
       +
       

     

       407
       407
       +
       	// Try to parse with indigo's crypto package

     

       408
       408
       +
       	pubKey, err := indigoCrypto.ParsePublicJWKBytes(jwkBytes)

     

       409
       409
       +
       	if err != nil {

     

       410
       410
       +
       		return nil, fmt.Errorf("failed to parse JWK: %w", err)

     

       411
       411
       +
       	}

     

       412
       412
       +
       

     

       413
       413
       +
       	// Convert indigo's PublicKey to Go's ecdsa.PublicKey

     

       414
       414
       +
       	jwk, err := pubKey.JWK()

     

       415
       415
       +
       	if err != nil {

     

       416
       416
       +
       		return nil, fmt.Errorf("failed to get JWK from public key: %w", err)

     

       417
       417
       +
       	}

     

       418
       418
       +
       

     

       419
       419
       +
       	// Use our existing conversion function

     

       420
       420
       +
       	return atcryptoJWKToECDSAFromIndigoJWK(jwk)

     

       421
       421
       +
       }

     

       422
       422
       +
       

     

       423
       423
       +
       // atcryptoJWKToECDSAFromIndigoJWK converts an indigo JWK to Go ecdsa.PublicKey

     

       424
       424
       +
       func atcryptoJWKToECDSAFromIndigoJWK(jwk *indigoCrypto.JWK) (*ecdsa.PublicKey, error) {

     

       425
       425
       +
       	if jwk.KeyType != "EC" {

     

       426
       426
       +
       		return nil, fmt.Errorf("unsupported JWK key type: %s (expected EC)", jwk.KeyType)

     

       427
       427
       +
       	}

     

       428
       428
       +
       

     

       429
       429
       +
       	xBytes, err := base64.RawURLEncoding.DecodeString(jwk.X)

     

       430
       430
       +
       	if err != nil {

     

       431
       431
       +
       		return nil, fmt.Errorf("invalid JWK X coordinate: %w", err)

     

       432
       432
       +
       	}

     

       433
       433
       +
       	yBytes, err := base64.RawURLEncoding.DecodeString(jwk.Y)

     

       434
       434
       +
       	if err != nil {

     

       435
       435
       +
       		return nil, fmt.Errorf("invalid JWK Y coordinate: %w", err)

     

       436
       436
       +
       	}

     

       437
       437
       +
       

     

       438
       438
       +
       	var curve ecdsa.PublicKey

     

       439
       439
       +
       	switch jwk.Curve {

     

       440
       440
       +
       	case "P-256":

     

       441
       441
       +
       		curve.Curve = ecdsaP256Curve()

     

       442
       442
       +
       	case "P-384":

     

       443
       443
       +
       		curve.Curve = ecdsaP384Curve()

     

       444
       444
       +
       	case "P-521":

     

       445
       445
       +
       		curve.Curve = ecdsaP521Curve()

     

       446
       446
       +
       	default:

     

       447
       447
       +
       		return nil, fmt.Errorf("unsupported curve: %s", jwk.Curve)

     

       448
       448
       +
       	}

     

       449
       449
       +
       

     

       450
       450
       +
       	curve.X = new(big.Int).SetBytes(xBytes)

     

       451
       451
       +
       	curve.Y = new(big.Int).SetBytes(yBytes)

     

       452
       452
       +
       

     

       453
       453
       +
       	return &curve, nil

     

       454
       454
       +
       }

     

       455
       455
       +
       

     

       456
       456
       +
       // Helper functions for elliptic curves

     

       457
       457
       +
       func ecdsaP256Curve() elliptic.Curve { return elliptic.P256() }

     

       458
       458
       +
       func ecdsaP384Curve() elliptic.Curve { return elliptic.P384() }

     

       459
       459
       +
       func ecdsaP521Curve() elliptic.Curve { return elliptic.P521() }

     

       460
       460
       +
       

     

       461
       461
       +
       // stripQueryFragment removes query and fragment from a URI

     

       462
       462
       +
       func stripQueryFragment(uri string) string {

     

       463
       463
       +
       	if idx := strings.Index(uri, "?"); idx != -1 {

     

       464
       464
       +
       		uri = uri[:idx]

     

       465
       465
       +
       	}

     

       466
       466
       +
       	if idx := strings.Index(uri, "#"); idx != -1 {

     

       467
       467
       +
       		uri = uri[:idx]

     

       468
       468
       +
       	}

     

       469
       469
       +
       	return uri

     

       470
       470
       +
       }

     

       471
       471
       +
       

     

       472
       472
       +
       // ExtractCnfJkt extracts the cnf.jkt (confirmation key thumbprint) from JWT claims

     

       473
       473
       +
       func ExtractCnfJkt(claims *Claims) (string, error) {

     

       474
       474
       +
       	if claims.Confirmation == nil {

     

       475
       475
       +
       		return "", fmt.Errorf("token missing cnf claim (no DPoP binding)")

     

       476
       476
       +
       	}

     

       477
       477
       +
       

     

       478
       478
       +
       	jkt, ok := claims.Confirmation["jkt"].(string)

     

       479
       479
       +
       	if !ok || jkt == "" {

     

       480
       480
       +
       		return "", fmt.Errorf("token cnf claim missing jkt (DPoP key thumbprint)")

     

       481
       481
       +
       	}

     

       482
       482
       +
       

     

       483
       483
       +
       	return jkt, nil

     

       484
       484
       +
       }

+921

internal/atproto/auth/dpop_test.go

···

       1
       1
       +
       package auth

     

       2
       2
       +
       

     

       3
       3
       +
       import (

     

       4
       4
       +
       	"crypto/ecdsa"

     

       5
       5
       +
       	"crypto/elliptic"

     

       6
       6
       +
       	"crypto/rand"

     

       7
       7
       +
       	"crypto/sha256"

     

       8
       8
       +
       	"encoding/base64"

     

       9
       9
       +
       	"encoding/json"

     

       10
       10
       +
       	"strings"

     

       11
       11
       +
       	"testing"

     

       12
       12
       +
       	"time"

     

       13
       13
       +
       

     

       14
       14
       +
       	"github.com/golang-jwt/jwt/v5"

     

       15
       15
       +
       	"github.com/google/uuid"

     

       16
       16
       +
       )

     

       17
       17
       +
       

     

       18
       18
       +
       // === Test Helpers ===

     

       19
       19
       +
       

     

       20
       20
       +
       // testECKey holds a test ES256 key pair

     

       21
       21
       +
       type testECKey struct {

     

       22
       22
       +
       	privateKey *ecdsa.PrivateKey

     

       23
       23
       +
       	publicKey  *ecdsa.PublicKey

     

       24
       24
       +
       	jwk        map[string]interface{}

     

       25
       25
       +
       	thumbprint string

     

       26
       26
       +
       }

     

       27
       27
       +
       

     

       28
       28
       +
       // generateTestES256Key generates a test ES256 key pair and JWK

     

       29
       29
       +
       func generateTestES256Key(t *testing.T) *testECKey {

     

       30
       30
       +
       	t.Helper()

     

       31
       31
       +
       

     

       32
       32
       +
       	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

     

       33
       33
       +
       	if err != nil {

     

       34
       34
       +
       		t.Fatalf("Failed to generate test key: %v", err)

     

       35
       35
       +
       	}

     

       36
       36
       +
       

     

       37
       37
       +
       	// Encode public key coordinates as base64url

     

       38
       38
       +
       	xBytes := privateKey.PublicKey.X.Bytes()

     

       39
       39
       +
       	yBytes := privateKey.PublicKey.Y.Bytes()

     

       40
       40
       +
       

     

       41
       41
       +
       	// P-256 coordinates must be 32 bytes (pad if needed)

     

       42
       42
       +
       	xBytes = padTo32Bytes(xBytes)

     

       43
       43
       +
       	yBytes = padTo32Bytes(yBytes)

     

       44
       44
       +
       

     

       45
       45
       +
       	x := base64.RawURLEncoding.EncodeToString(xBytes)

     

       46
       46
       +
       	y := base64.RawURLEncoding.EncodeToString(yBytes)

     

       47
       47
       +
       

     

       48
       48
       +
       	jwk := map[string]interface{}{

     

       49
       49
       +
       		"kty": "EC",

     

       50
       50
       +
       		"crv": "P-256",

     

       51
       51
       +
       		"x":   x,

     

       52
       52
       +
       		"y":   y,

     

       53
       53
       +
       	}

     

       54
       54
       +
       

     

       55
       55
       +
       	// Calculate thumbprint

     

       56
       56
       +
       	thumbprint, err := CalculateJWKThumbprint(jwk)

     

       57
       57
       +
       	if err != nil {

     

       58
       58
       +
       		t.Fatalf("Failed to calculate thumbprint: %v", err)

     

       59
       59
       +
       	}

     

       60
       60
       +
       

     

       61
       61
       +
       	return &testECKey{

     

       62
       62
       +
       		privateKey: privateKey,

     

       63
       63
       +
       		publicKey:  &privateKey.PublicKey,

     

       64
       64
       +
       		jwk:        jwk,

     

       65
       65
       +
       		thumbprint: thumbprint,

     

       66
       66
       +
       	}

     

       67
       67
       +
       }

     

       68
       68
       +
       

     

       69
       69
       +
       // padTo32Bytes pads a byte slice to 32 bytes (required for P-256 coordinates)

     

       70
       70
       +
       func padTo32Bytes(b []byte) []byte {

     

       71
       71
       +
       	if len(b) >= 32 {

     

       72
       72
       +
       		return b

     

       73
       73
       +
       	}

     

       74
       74
       +
       	padded := make([]byte, 32)

     

       75
       75
       +
       	copy(padded[32-len(b):], b)

     

       76
       76
       +
       	return padded

     

       77
       77
       +
       }

     

       78
       78
       +
       

     

       79
       79
       +
       // createDPoPProof creates a DPoP proof JWT for testing

     

       80
       80
       +
       func createDPoPProof(t *testing.T, key *testECKey, method, uri string, iat time.Time, jti string) string {

     

       81
       81
       +
       	t.Helper()

     

       82
       82
       +
       

     

       83
       83
       +
       	claims := &DPoPClaims{

     

       84
       84
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       85
       85
       +
       			ID:       jti,

     

       86
       86
       +
       			IssuedAt: jwt.NewNumericDate(iat),

     

       87
       87
       +
       		},

     

       88
       88
       +
       		HTTPMethod: method,

     

       89
       89
       +
       		HTTPURI:    uri,

     

       90
       90
       +
       	}

     

       91
       91
       +
       

     

       92
       92
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       93
       93
       +
       	token.Header["typ"] = "dpop+jwt"

     

       94
       94
       +
       	token.Header["jwk"] = key.jwk

     

       95
       95
       +
       

     

       96
       96
       +
       	tokenString, err := token.SignedString(key.privateKey)

     

       97
       97
       +
       	if err != nil {

     

       98
       98
       +
       		t.Fatalf("Failed to create DPoP proof: %v", err)

     

       99
       99
       +
       	}

     

       100
       100
       +
       

     

       101
       101
       +
       	return tokenString

     

       102
       102
       +
       }

     

       103
       103
       +
       

     

       104
       104
       +
       // === JWK Thumbprint Tests (RFC 7638) ===

     

       105
       105
       +
       

     

       106
       106
       +
       func TestCalculateJWKThumbprint_EC_P256(t *testing.T) {

     

       107
       107
       +
       	// Test with known values from RFC 7638 Appendix A (adapted for P-256)

     

       108
       108
       +
       	jwk := map[string]interface{}{

     

       109
       109
       +
       		"kty": "EC",

     

       110
       110
       +
       		"crv": "P-256",

     

       111
       111
       +
       		"x":   "WKn-ZIGevcwGIyyrzFoZNBdaq9_TsqzGl96oc0CWuis",

     

       112
       112
       +
       		"y":   "y77t-RvAHRKTsSGdIYUfweuOvwrvDD-Q3Hv5J0fSKbE",

     

       113
       113
       +
       	}

     

       114
       114
       +
       

     

       115
       115
       +
       	thumbprint, err := CalculateJWKThumbprint(jwk)

     

       116
       116
       +
       	if err != nil {

     

       117
       117
       +
       		t.Fatalf("CalculateJWKThumbprint failed: %v", err)

     

       118
       118
       +
       	}

     

       119
       119
       +
       

     

       120
       120
       +
       	if thumbprint == "" {

     

       121
       121
       +
       		t.Error("Expected non-empty thumbprint")

     

       122
       122
       +
       	}

     

       123
       123
       +
       

     

       124
       124
       +
       	// Verify it's valid base64url

     

       125
       125
       +
       	_, err = base64.RawURLEncoding.DecodeString(thumbprint)

     

       126
       126
       +
       	if err != nil {

     

       127
       127
       +
       		t.Errorf("Thumbprint is not valid base64url: %v", err)

     

       128
       128
       +
       	}

     

       129
       129
       +
       

     

       130
       130
       +
       	// Verify length (SHA-256 produces 32 bytes = 43 base64url chars)

     

       131
       131
       +
       	if len(thumbprint) != 43 {

     

       132
       132
       +
       		t.Errorf("Expected thumbprint length 43, got %d", len(thumbprint))

     

       133
       133
       +
       	}

     

       134
       134
       +
       }

     

       135
       135
       +
       

     

       136
       136
       +
       func TestCalculateJWKThumbprint_Deterministic(t *testing.T) {

     

       137
       137
       +
       	// Same key should produce same thumbprint

     

       138
       138
       +
       	jwk := map[string]interface{}{

     

       139
       139
       +
       		"kty": "EC",

     

       140
       140
       +
       		"crv": "P-256",

     

       141
       141
       +
       		"x":   "test-x-coordinate",

     

       142
       142
       +
       		"y":   "test-y-coordinate",

     

       143
       143
       +
       	}

     

       144
       144
       +
       

     

       145
       145
       +
       	thumbprint1, err := CalculateJWKThumbprint(jwk)

     

       146
       146
       +
       	if err != nil {

     

       147
       147
       +
       		t.Fatalf("First CalculateJWKThumbprint failed: %v", err)

     

       148
       148
       +
       	}

     

       149
       149
       +
       

     

       150
       150
       +
       	thumbprint2, err := CalculateJWKThumbprint(jwk)

     

       151
       151
       +
       	if err != nil {

     

       152
       152
       +
       		t.Fatalf("Second CalculateJWKThumbprint failed: %v", err)

     

       153
       153
       +
       	}

     

       154
       154
       +
       

     

       155
       155
       +
       	if thumbprint1 != thumbprint2 {

     

       156
       156
       +
       		t.Errorf("Thumbprints are not deterministic: %s != %s", thumbprint1, thumbprint2)

     

       157
       157
       +
       	}

     

       158
       158
       +
       }

     

       159
       159
       +
       

     

       160
       160
       +
       func TestCalculateJWKThumbprint_DifferentKeys(t *testing.T) {

     

       161
       161
       +
       	// Different keys should produce different thumbprints

     

       162
       162
       +
       	jwk1 := map[string]interface{}{

     

       163
       163
       +
       		"kty": "EC",

     

       164
       164
       +
       		"crv": "P-256",

     

       165
       165
       +
       		"x":   "coordinate-x-1",

     

       166
       166
       +
       		"y":   "coordinate-y-1",

     

       167
       167
       +
       	}

     

       168
       168
       +
       

     

       169
       169
       +
       	jwk2 := map[string]interface{}{

     

       170
       170
       +
       		"kty": "EC",

     

       171
       171
       +
       		"crv": "P-256",

     

       172
       172
       +
       		"x":   "coordinate-x-2",

     

       173
       173
       +
       		"y":   "coordinate-y-2",

     

       174
       174
       +
       	}

     

       175
       175
       +
       

     

       176
       176
       +
       	thumbprint1, err := CalculateJWKThumbprint(jwk1)

     

       177
       177
       +
       	if err != nil {

     

       178
       178
       +
       		t.Fatalf("First CalculateJWKThumbprint failed: %v", err)

     

       179
       179
       +
       	}

     

       180
       180
       +
       

     

       181
       181
       +
       	thumbprint2, err := CalculateJWKThumbprint(jwk2)

     

       182
       182
       +
       	if err != nil {

     

       183
       183
       +
       		t.Fatalf("Second CalculateJWKThumbprint failed: %v", err)

     

       184
       184
       +
       	}

     

       185
       185
       +
       

     

       186
       186
       +
       	if thumbprint1 == thumbprint2 {

     

       187
       187
       +
       		t.Error("Different keys produced same thumbprint (collision)")

     

       188
       188
       +
       	}

     

       189
       189
       +
       }

     

       190
       190
       +
       

     

       191
       191
       +
       func TestCalculateJWKThumbprint_MissingKty(t *testing.T) {

     

       192
       192
       +
       	jwk := map[string]interface{}{

     

       193
       193
       +
       		"crv": "P-256",

     

       194
       194
       +
       		"x":   "test-x",

     

       195
       195
       +
       		"y":   "test-y",

     

       196
       196
       +
       	}

     

       197
       197
       +
       

     

       198
       198
       +
       	_, err := CalculateJWKThumbprint(jwk)

     

       199
       199
       +
       	if err == nil {

     

       200
       200
       +
       		t.Error("Expected error for missing kty, got nil")

     

       201
       201
       +
       	}

     

       202
       202
       +
       	if err != nil && !contains(err.Error(), "missing kty") {

     

       203
       203
       +
       		t.Errorf("Expected error about missing kty, got: %v", err)

     

       204
       204
       +
       	}

     

       205
       205
       +
       }

     

       206
       206
       +
       

     

       207
       207
       +
       func TestCalculateJWKThumbprint_EC_MissingCrv(t *testing.T) {

     

       208
       208
       +
       	jwk := map[string]interface{}{

     

       209
       209
       +
       		"kty": "EC",

     

       210
       210
       +
       		"x":   "test-x",

     

       211
       211
       +
       		"y":   "test-y",

     

       212
       212
       +
       	}

     

       213
       213
       +
       

     

       214
       214
       +
       	_, err := CalculateJWKThumbprint(jwk)

     

       215
       215
       +
       	if err == nil {

     

       216
       216
       +
       		t.Error("Expected error for missing crv, got nil")

     

       217
       217
       +
       	}

     

       218
       218
       +
       	if err != nil && !contains(err.Error(), "missing crv") {

     

       219
       219
       +
       		t.Errorf("Expected error about missing crv, got: %v", err)

     

       220
       220
       +
       	}

     

       221
       221
       +
       }

     

       222
       222
       +
       

     

       223
       223
       +
       func TestCalculateJWKThumbprint_EC_MissingX(t *testing.T) {

     

       224
       224
       +
       	jwk := map[string]interface{}{

     

       225
       225
       +
       		"kty": "EC",

     

       226
       226
       +
       		"crv": "P-256",

     

       227
       227
       +
       		"y":   "test-y",

     

       228
       228
       +
       	}

     

       229
       229
       +
       

     

       230
       230
       +
       	_, err := CalculateJWKThumbprint(jwk)

     

       231
       231
       +
       	if err == nil {

     

       232
       232
       +
       		t.Error("Expected error for missing x, got nil")

     

       233
       233
       +
       	}

     

       234
       234
       +
       	if err != nil && !contains(err.Error(), "missing x") {

     

       235
       235
       +
       		t.Errorf("Expected error about missing x, got: %v", err)

     

       236
       236
       +
       	}

     

       237
       237
       +
       }

     

       238
       238
       +
       

     

       239
       239
       +
       func TestCalculateJWKThumbprint_EC_MissingY(t *testing.T) {

     

       240
       240
       +
       	jwk := map[string]interface{}{

     

       241
       241
       +
       		"kty": "EC",

     

       242
       242
       +
       		"crv": "P-256",

     

       243
       243
       +
       		"x":   "test-x",

     

       244
       244
       +
       	}

     

       245
       245
       +
       

     

       246
       246
       +
       	_, err := CalculateJWKThumbprint(jwk)

     

       247
       247
       +
       	if err == nil {

     

       248
       248
       +
       		t.Error("Expected error for missing y, got nil")

     

       249
       249
       +
       	}

     

       250
       250
       +
       	if err != nil && !contains(err.Error(), "missing y") {

     

       251
       251
       +
       		t.Errorf("Expected error about missing y, got: %v", err)

     

       252
       252
       +
       	}

     

       253
       253
       +
       }

     

       254
       254
       +
       

     

       255
       255
       +
       func TestCalculateJWKThumbprint_RSA(t *testing.T) {

     

       256
       256
       +
       	// Test RSA key thumbprint calculation

     

       257
       257
       +
       	jwk := map[string]interface{}{

     

       258
       258
       +
       		"kty": "RSA",

     

       259
       259
       +
       		"e":   "AQAB",

     

       260
       260
       +
       		"n":   "test-modulus",

     

       261
       261
       +
       	}

     

       262
       262
       +
       

     

       263
       263
       +
       	thumbprint, err := CalculateJWKThumbprint(jwk)

     

       264
       264
       +
       	if err != nil {

     

       265
       265
       +
       		t.Fatalf("CalculateJWKThumbprint failed for RSA: %v", err)

     

       266
       266
       +
       	}

     

       267
       267
       +
       

     

       268
       268
       +
       	if thumbprint == "" {

     

       269
       269
       +
       		t.Error("Expected non-empty thumbprint for RSA key")

     

       270
       270
       +
       	}

     

       271
       271
       +
       }

     

       272
       272
       +
       

     

       273
       273
       +
       func TestCalculateJWKThumbprint_OKP(t *testing.T) {

     

       274
       274
       +
       	// Test OKP (Octet Key Pair) thumbprint calculation

     

       275
       275
       +
       	jwk := map[string]interface{}{

     

       276
       276
       +
       		"kty": "OKP",

     

       277
       277
       +
       		"crv": "Ed25519",

     

       278
       278
       +
       		"x":   "test-x-coordinate",

     

       279
       279
       +
       	}

     

       280
       280
       +
       

     

       281
       281
       +
       	thumbprint, err := CalculateJWKThumbprint(jwk)

     

       282
       282
       +
       	if err != nil {

     

       283
       283
       +
       		t.Fatalf("CalculateJWKThumbprint failed for OKP: %v", err)

     

       284
       284
       +
       	}

     

       285
       285
       +
       

     

       286
       286
       +
       	if thumbprint == "" {

     

       287
       287
       +
       		t.Error("Expected non-empty thumbprint for OKP key")

     

       288
       288
       +
       	}

     

       289
       289
       +
       }

     

       290
       290
       +
       

     

       291
       291
       +
       func TestCalculateJWKThumbprint_UnsupportedKeyType(t *testing.T) {

     

       292
       292
       +
       	jwk := map[string]interface{}{

     

       293
       293
       +
       		"kty": "UNKNOWN",

     

       294
       294
       +
       	}

     

       295
       295
       +
       

     

       296
       296
       +
       	_, err := CalculateJWKThumbprint(jwk)

     

       297
       297
       +
       	if err == nil {

     

       298
       298
       +
       		t.Error("Expected error for unsupported key type, got nil")

     

       299
       299
       +
       	}

     

       300
       300
       +
       	if err != nil && !contains(err.Error(), "unsupported JWK key type") {

     

       301
       301
       +
       		t.Errorf("Expected error about unsupported key type, got: %v", err)

     

       302
       302
       +
       	}

     

       303
       303
       +
       }

     

       304
       304
       +
       

     

       305
       305
       +
       func TestCalculateJWKThumbprint_CanonicalJSON(t *testing.T) {

     

       306
       306
       +
       	// RFC 7638 requires lexicographic ordering of keys in canonical JSON

     

       307
       307
       +
       	// This test verifies that the canonical JSON is correctly ordered

     

       308
       308
       +
       

     

       309
       309
       +
       	jwk := map[string]interface{}{

     

       310
       310
       +
       		"kty": "EC",

     

       311
       311
       +
       		"crv": "P-256",

     

       312
       312
       +
       		"x":   "x-coord",

     

       313
       313
       +
       		"y":   "y-coord",

     

       314
       314
       +
       	}

     

       315
       315
       +
       

     

       316
       316
       +
       	// The canonical JSON should be: {"crv":"P-256","kty":"EC","x":"x-coord","y":"y-coord"}

     

       317
       317
       +
       	// (lexicographically ordered: crv, kty, x, y)

     

       318
       318
       +
       

     

       319
       319
       +
       	canonical := map[string]string{

     

       320
       320
       +
       		"crv": "P-256",

     

       321
       321
       +
       		"kty": "EC",

     

       322
       322
       +
       		"x":   "x-coord",

     

       323
       323
       +
       		"y":   "y-coord",

     

       324
       324
       +
       	}

     

       325
       325
       +
       

     

       326
       326
       +
       	canonicalJSON, err := json.Marshal(canonical)

     

       327
       327
       +
       	if err != nil {

     

       328
       328
       +
       		t.Fatalf("Failed to marshal canonical JSON: %v", err)

     

       329
       329
       +
       	}

     

       330
       330
       +
       

     

       331
       331
       +
       	expectedHash := sha256.Sum256(canonicalJSON)

     

       332
       332
       +
       	expectedThumbprint := base64.RawURLEncoding.EncodeToString(expectedHash[:])

     

       333
       333
       +
       

     

       334
       334
       +
       	actualThumbprint, err := CalculateJWKThumbprint(jwk)

     

       335
       335
       +
       	if err != nil {

     

       336
       336
       +
       		t.Fatalf("CalculateJWKThumbprint failed: %v", err)

     

       337
       337
       +
       	}

     

       338
       338
       +
       

     

       339
       339
       +
       	if actualThumbprint != expectedThumbprint {

     

       340
       340
       +
       		t.Errorf("Thumbprint doesn't match expected canonical JSON hash\nExpected: %s\nGot: %s",

     

       341
       341
       +
       			expectedThumbprint, actualThumbprint)

     

       342
       342
       +
       	}

     

       343
       343
       +
       }

     

       344
       344
       +
       

     

       345
       345
       +
       // === DPoP Proof Verification Tests ===

     

       346
       346
       +
       

     

       347
       347
       +
       func TestVerifyDPoPProof_Valid(t *testing.T) {

     

       348
       348
       +
       	verifier := NewDPoPVerifier()

     

       349
       349
       +
       	key := generateTestES256Key(t)

     

       350
       350
       +
       

     

       351
       351
       +
       	method := "POST"

     

       352
       352
       +
       	uri := "https://api.example.com/resource"

     

       353
       353
       +
       	iat := time.Now()

     

       354
       354
       +
       	jti := uuid.New().String()

     

       355
       355
       +
       

     

       356
       356
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       357
       357
       +
       

     

       358
       358
       +
       	result, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       359
       359
       +
       	if err != nil {

     

       360
       360
       +
       		t.Fatalf("VerifyDPoPProof failed for valid proof: %v", err)

     

       361
       361
       +
       	}

     

       362
       362
       +
       

     

       363
       363
       +
       	if result == nil {

     

       364
       364
       +
       		t.Fatal("Expected non-nil proof result")

     

       365
       365
       +
       	}

     

       366
       366
       +
       

     

       367
       367
       +
       	if result.Claims.HTTPMethod != method {

     

       368
       368
       +
       		t.Errorf("Expected method %s, got %s", method, result.Claims.HTTPMethod)

     

       369
       369
       +
       	}

     

       370
       370
       +
       

     

       371
       371
       +
       	if result.Claims.HTTPURI != uri {

     

       372
       372
       +
       		t.Errorf("Expected URI %s, got %s", uri, result.Claims.HTTPURI)

     

       373
       373
       +
       	}

     

       374
       374
       +
       

     

       375
       375
       +
       	if result.Claims.ID != jti {

     

       376
       376
       +
       		t.Errorf("Expected jti %s, got %s", jti, result.Claims.ID)

     

       377
       377
       +
       	}

     

       378
       378
       +
       

     

       379
       379
       +
       	if result.Thumbprint != key.thumbprint {

     

       380
       380
       +
       		t.Errorf("Expected thumbprint %s, got %s", key.thumbprint, result.Thumbprint)

     

       381
       381
       +
       	}

     

       382
       382
       +
       }

     

       383
       383
       +
       

     

       384
       384
       +
       func TestVerifyDPoPProof_InvalidSignature(t *testing.T) {

     

       385
       385
       +
       	verifier := NewDPoPVerifier()

     

       386
       386
       +
       	key := generateTestES256Key(t)

     

       387
       387
       +
       	wrongKey := generateTestES256Key(t)

     

       388
       388
       +
       

     

       389
       389
       +
       	method := "POST"

     

       390
       390
       +
       	uri := "https://api.example.com/resource"

     

       391
       391
       +
       	iat := time.Now()

     

       392
       392
       +
       	jti := uuid.New().String()

     

       393
       393
       +
       

     

       394
       394
       +
       	// Create proof with one key

     

       395
       395
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       396
       396
       +
       

     

       397
       397
       +
       	// Parse and modify to use wrong key's JWK in header (signature won't match)

     

       398
       398
       +
       	parts := splitJWT(proof)

     

       399
       399
       +
       	header := parseJWTHeader(t, parts[0])

     

       400
       400
       +
       	header["jwk"] = wrongKey.jwk

     

       401
       401
       +
       	modifiedHeader := encodeJSON(t, header)

     

       402
       402
       +
       	tamperedProof := modifiedHeader + "." + parts[1] + "." + parts[2]

     

       403
       403
       +
       

     

       404
       404
       +
       	_, err := verifier.VerifyDPoPProof(tamperedProof, method, uri)

     

       405
       405
       +
       	if err == nil {

     

       406
       406
       +
       		t.Error("Expected error for invalid signature, got nil")

     

       407
       407
       +
       	}

     

       408
       408
       +
       	if err != nil && !contains(err.Error(), "signature verification failed") {

     

       409
       409
       +
       		t.Errorf("Expected signature verification error, got: %v", err)

     

       410
       410
       +
       	}

     

       411
       411
       +
       }

     

       412
       412
       +
       

     

       413
       413
       +
       func TestVerifyDPoPProof_WrongHTTPMethod(t *testing.T) {

     

       414
       414
       +
       	verifier := NewDPoPVerifier()

     

       415
       415
       +
       	key := generateTestES256Key(t)

     

       416
       416
       +
       

     

       417
       417
       +
       	method := "POST"

     

       418
       418
       +
       	wrongMethod := "GET"

     

       419
       419
       +
       	uri := "https://api.example.com/resource"

     

       420
       420
       +
       	iat := time.Now()

     

       421
       421
       +
       	jti := uuid.New().String()

     

       422
       422
       +
       

     

       423
       423
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       424
       424
       +
       

     

       425
       425
       +
       	_, err := verifier.VerifyDPoPProof(proof, wrongMethod, uri)

     

       426
       426
       +
       	if err == nil {

     

       427
       427
       +
       		t.Error("Expected error for HTTP method mismatch, got nil")

     

       428
       428
       +
       	}

     

       429
       429
       +
       	if err != nil && !contains(err.Error(), "htm mismatch") {

     

       430
       430
       +
       		t.Errorf("Expected htm mismatch error, got: %v", err)

     

       431
       431
       +
       	}

     

       432
       432
       +
       }

     

       433
       433
       +
       

     

       434
       434
       +
       func TestVerifyDPoPProof_WrongURI(t *testing.T) {

     

       435
       435
       +
       	verifier := NewDPoPVerifier()

     

       436
       436
       +
       	key := generateTestES256Key(t)

     

       437
       437
       +
       

     

       438
       438
       +
       	method := "POST"

     

       439
       439
       +
       	uri := "https://api.example.com/resource"

     

       440
       440
       +
       	wrongURI := "https://api.example.com/different"

     

       441
       441
       +
       	iat := time.Now()

     

       442
       442
       +
       	jti := uuid.New().String()

     

       443
       443
       +
       

     

       444
       444
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       445
       445
       +
       

     

       446
       446
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, wrongURI)

     

       447
       447
       +
       	if err == nil {

     

       448
       448
       +
       		t.Error("Expected error for URI mismatch, got nil")

     

       449
       449
       +
       	}

     

       450
       450
       +
       	if err != nil && !contains(err.Error(), "htu mismatch") {

     

       451
       451
       +
       		t.Errorf("Expected htu mismatch error, got: %v", err)

     

       452
       452
       +
       	}

     

       453
       453
       +
       }

     

       454
       454
       +
       

     

       455
       455
       +
       func TestVerifyDPoPProof_URIWithQuery(t *testing.T) {

     

       456
       456
       +
       	// URI comparison should strip query and fragment

     

       457
       457
       +
       	verifier := NewDPoPVerifier()

     

       458
       458
       +
       	key := generateTestES256Key(t)

     

       459
       459
       +
       

     

       460
       460
       +
       	method := "POST"

     

       461
       461
       +
       	baseURI := "https://api.example.com/resource"

     

       462
       462
       +
       	uriWithQuery := baseURI + "?param=value"

     

       463
       463
       +
       	iat := time.Now()

     

       464
       464
       +
       	jti := uuid.New().String()

     

       465
       465
       +
       

     

       466
       466
       +
       	proof := createDPoPProof(t, key, method, baseURI, iat, jti)

     

       467
       467
       +
       

     

       468
       468
       +
       	// Should succeed because query is stripped

     

       469
       469
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uriWithQuery)

     

       470
       470
       +
       	if err != nil {

     

       471
       471
       +
       		t.Fatalf("VerifyDPoPProof failed for URI with query: %v", err)

     

       472
       472
       +
       	}

     

       473
       473
       +
       }

     

       474
       474
       +
       

     

       475
       475
       +
       func TestVerifyDPoPProof_URIWithFragment(t *testing.T) {

     

       476
       476
       +
       	// URI comparison should strip query and fragment

     

       477
       477
       +
       	verifier := NewDPoPVerifier()

     

       478
       478
       +
       	key := generateTestES256Key(t)

     

       479
       479
       +
       

     

       480
       480
       +
       	method := "POST"

     

       481
       481
       +
       	baseURI := "https://api.example.com/resource"

     

       482
       482
       +
       	uriWithFragment := baseURI + "#section"

     

       483
       483
       +
       	iat := time.Now()

     

       484
       484
       +
       	jti := uuid.New().String()

     

       485
       485
       +
       

     

       486
       486
       +
       	proof := createDPoPProof(t, key, method, baseURI, iat, jti)

     

       487
       487
       +
       

     

       488
       488
       +
       	// Should succeed because fragment is stripped

     

       489
       489
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uriWithFragment)

     

       490
       490
       +
       	if err != nil {

     

       491
       491
       +
       		t.Fatalf("VerifyDPoPProof failed for URI with fragment: %v", err)

     

       492
       492
       +
       	}

     

       493
       493
       +
       }

     

       494
       494
       +
       

     

       495
       495
       +
       func TestVerifyDPoPProof_ExpiredProof(t *testing.T) {

     

       496
       496
       +
       	verifier := NewDPoPVerifier()

     

       497
       497
       +
       	key := generateTestES256Key(t)

     

       498
       498
       +
       

     

       499
       499
       +
       	method := "POST"

     

       500
       500
       +
       	uri := "https://api.example.com/resource"

     

       501
       501
       +
       	// Proof issued 10 minutes ago (exceeds default MaxProofAge of 5 minutes)

     

       502
       502
       +
       	iat := time.Now().Add(-10 * time.Minute)

     

       503
       503
       +
       	jti := uuid.New().String()

     

       504
       504
       +
       

     

       505
       505
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       506
       506
       +
       

     

       507
       507
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       508
       508
       +
       	if err == nil {

     

       509
       509
       +
       		t.Error("Expected error for expired proof, got nil")

     

       510
       510
       +
       	}

     

       511
       511
       +
       	if err != nil && !contains(err.Error(), "too old") {

     

       512
       512
       +
       		t.Errorf("Expected 'too old' error, got: %v", err)

     

       513
       513
       +
       	}

     

       514
       514
       +
       }

     

       515
       515
       +
       

     

       516
       516
       +
       func TestVerifyDPoPProof_FutureProof(t *testing.T) {

     

       517
       517
       +
       	verifier := NewDPoPVerifier()

     

       518
       518
       +
       	key := generateTestES256Key(t)

     

       519
       519
       +
       

     

       520
       520
       +
       	method := "POST"

     

       521
       521
       +
       	uri := "https://api.example.com/resource"

     

       522
       522
       +
       	// Proof issued 1 minute in the future (exceeds MaxClockSkew)

     

       523
       523
       +
       	iat := time.Now().Add(1 * time.Minute)

     

       524
       524
       +
       	jti := uuid.New().String()

     

       525
       525
       +
       

     

       526
       526
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       527
       527
       +
       

     

       528
       528
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       529
       529
       +
       	if err == nil {

     

       530
       530
       +
       		t.Error("Expected error for future proof, got nil")

     

       531
       531
       +
       	}

     

       532
       532
       +
       	if err != nil && !contains(err.Error(), "in the future") {

     

       533
       533
       +
       		t.Errorf("Expected 'in the future' error, got: %v", err)

     

       534
       534
       +
       	}

     

       535
       535
       +
       }

     

       536
       536
       +
       

     

       537
       537
       +
       func TestVerifyDPoPProof_WithinClockSkew(t *testing.T) {

     

       538
       538
       +
       	verifier := NewDPoPVerifier()

     

       539
       539
       +
       	key := generateTestES256Key(t)

     

       540
       540
       +
       

     

       541
       541
       +
       	method := "POST"

     

       542
       542
       +
       	uri := "https://api.example.com/resource"

     

       543
       543
       +
       	// Proof issued 15 seconds in the future (within MaxClockSkew of 30s)

     

       544
       544
       +
       	iat := time.Now().Add(15 * time.Second)

     

       545
       545
       +
       	jti := uuid.New().String()

     

       546
       546
       +
       

     

       547
       547
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       548
       548
       +
       

     

       549
       549
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       550
       550
       +
       	if err != nil {

     

       551
       551
       +
       		t.Fatalf("VerifyDPoPProof failed for proof within clock skew: %v", err)

     

       552
       552
       +
       	}

     

       553
       553
       +
       }

     

       554
       554
       +
       

     

       555
       555
       +
       func TestVerifyDPoPProof_MissingJti(t *testing.T) {

     

       556
       556
       +
       	verifier := NewDPoPVerifier()

     

       557
       557
       +
       	key := generateTestES256Key(t)

     

       558
       558
       +
       

     

       559
       559
       +
       	method := "POST"

     

       560
       560
       +
       	uri := "https://api.example.com/resource"

     

       561
       561
       +
       	iat := time.Now()

     

       562
       562
       +
       

     

       563
       563
       +
       	claims := &DPoPClaims{

     

       564
       564
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       565
       565
       +
       			// No ID (jti)

     

       566
       566
       +
       			IssuedAt: jwt.NewNumericDate(iat),

     

       567
       567
       +
       		},

     

       568
       568
       +
       		HTTPMethod: method,

     

       569
       569
       +
       		HTTPURI:    uri,

     

       570
       570
       +
       	}

     

       571
       571
       +
       

     

       572
       572
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       573
       573
       +
       	token.Header["typ"] = "dpop+jwt"

     

       574
       574
       +
       	token.Header["jwk"] = key.jwk

     

       575
       575
       +
       

     

       576
       576
       +
       	proof, err := token.SignedString(key.privateKey)

     

       577
       577
       +
       	if err != nil {

     

       578
       578
       +
       		t.Fatalf("Failed to create test proof: %v", err)

     

       579
       579
       +
       	}

     

       580
       580
       +
       

     

       581
       581
       +
       	_, err = verifier.VerifyDPoPProof(proof, method, uri)

     

       582
       582
       +
       	if err == nil {

     

       583
       583
       +
       		t.Error("Expected error for missing jti, got nil")

     

       584
       584
       +
       	}

     

       585
       585
       +
       	if err != nil && !contains(err.Error(), "missing jti") {

     

       586
       586
       +
       		t.Errorf("Expected missing jti error, got: %v", err)

     

       587
       587
       +
       	}

     

       588
       588
       +
       }

     

       589
       589
       +
       

     

       590
       590
       +
       func TestVerifyDPoPProof_MissingTypHeader(t *testing.T) {

     

       591
       591
       +
       	verifier := NewDPoPVerifier()

     

       592
       592
       +
       	key := generateTestES256Key(t)

     

       593
       593
       +
       

     

       594
       594
       +
       	method := "POST"

     

       595
       595
       +
       	uri := "https://api.example.com/resource"

     

       596
       596
       +
       	iat := time.Now()

     

       597
       597
       +
       	jti := uuid.New().String()

     

       598
       598
       +
       

     

       599
       599
       +
       	claims := &DPoPClaims{

     

       600
       600
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       601
       601
       +
       			ID:       jti,

     

       602
       602
       +
       			IssuedAt: jwt.NewNumericDate(iat),

     

       603
       603
       +
       		},

     

       604
       604
       +
       		HTTPMethod: method,

     

       605
       605
       +
       		HTTPURI:    uri,

     

       606
       606
       +
       	}

     

       607
       607
       +
       

     

       608
       608
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       609
       609
       +
       	// Don't set typ header

     

       610
       610
       +
       	token.Header["jwk"] = key.jwk

     

       611
       611
       +
       

     

       612
       612
       +
       	proof, err := token.SignedString(key.privateKey)

     

       613
       613
       +
       	if err != nil {

     

       614
       614
       +
       		t.Fatalf("Failed to create test proof: %v", err)

     

       615
       615
       +
       	}

     

       616
       616
       +
       

     

       617
       617
       +
       	_, err = verifier.VerifyDPoPProof(proof, method, uri)

     

       618
       618
       +
       	if err == nil {

     

       619
       619
       +
       		t.Error("Expected error for missing typ header, got nil")

     

       620
       620
       +
       	}

     

       621
       621
       +
       	if err != nil && !contains(err.Error(), "typ must be 'dpop+jwt'") {

     

       622
       622
       +
       		t.Errorf("Expected typ header error, got: %v", err)

     

       623
       623
       +
       	}

     

       624
       624
       +
       }

     

       625
       625
       +
       

     

       626
       626
       +
       func TestVerifyDPoPProof_WrongTypHeader(t *testing.T) {

     

       627
       627
       +
       	verifier := NewDPoPVerifier()

     

       628
       628
       +
       	key := generateTestES256Key(t)

     

       629
       629
       +
       

     

       630
       630
       +
       	method := "POST"

     

       631
       631
       +
       	uri := "https://api.example.com/resource"

     

       632
       632
       +
       	iat := time.Now()

     

       633
       633
       +
       	jti := uuid.New().String()

     

       634
       634
       +
       

     

       635
       635
       +
       	claims := &DPoPClaims{

     

       636
       636
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       637
       637
       +
       			ID:       jti,

     

       638
       638
       +
       			IssuedAt: jwt.NewNumericDate(iat),

     

       639
       639
       +
       		},

     

       640
       640
       +
       		HTTPMethod: method,

     

       641
       641
       +
       		HTTPURI:    uri,

     

       642
       642
       +
       	}

     

       643
       643
       +
       

     

       644
       644
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       645
       645
       +
       	token.Header["typ"] = "JWT" // Wrong typ

     

       646
       646
       +
       	token.Header["jwk"] = key.jwk

     

       647
       647
       +
       

     

       648
       648
       +
       	proof, err := token.SignedString(key.privateKey)

     

       649
       649
       +
       	if err != nil {

     

       650
       650
       +
       		t.Fatalf("Failed to create test proof: %v", err)

     

       651
       651
       +
       	}

     

       652
       652
       +
       

     

       653
       653
       +
       	_, err = verifier.VerifyDPoPProof(proof, method, uri)

     

       654
       654
       +
       	if err == nil {

     

       655
       655
       +
       		t.Error("Expected error for wrong typ header, got nil")

     

       656
       656
       +
       	}

     

       657
       657
       +
       	if err != nil && !contains(err.Error(), "typ must be 'dpop+jwt'") {

     

       658
       658
       +
       		t.Errorf("Expected typ header error, got: %v", err)

     

       659
       659
       +
       	}

     

       660
       660
       +
       }

     

       661
       661
       +
       

     

       662
       662
       +
       func TestVerifyDPoPProof_MissingJWK(t *testing.T) {

     

       663
       663
       +
       	verifier := NewDPoPVerifier()

     

       664
       664
       +
       	key := generateTestES256Key(t)

     

       665
       665
       +
       

     

       666
       666
       +
       	method := "POST"

     

       667
       667
       +
       	uri := "https://api.example.com/resource"

     

       668
       668
       +
       	iat := time.Now()

     

       669
       669
       +
       	jti := uuid.New().String()

     

       670
       670
       +
       

     

       671
       671
       +
       	claims := &DPoPClaims{

     

       672
       672
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       673
       673
       +
       			ID:       jti,

     

       674
       674
       +
       			IssuedAt: jwt.NewNumericDate(iat),

     

       675
       675
       +
       		},

     

       676
       676
       +
       		HTTPMethod: method,

     

       677
       677
       +
       		HTTPURI:    uri,

     

       678
       678
       +
       	}

     

       679
       679
       +
       

     

       680
       680
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       681
       681
       +
       	token.Header["typ"] = "dpop+jwt"

     

       682
       682
       +
       	// Don't include JWK

     

       683
       683
       +
       

     

       684
       684
       +
       	proof, err := token.SignedString(key.privateKey)

     

       685
       685
       +
       	if err != nil {

     

       686
       686
       +
       		t.Fatalf("Failed to create test proof: %v", err)

     

       687
       687
       +
       	}

     

       688
       688
       +
       

     

       689
       689
       +
       	_, err = verifier.VerifyDPoPProof(proof, method, uri)

     

       690
       690
       +
       	if err == nil {

     

       691
       691
       +
       		t.Error("Expected error for missing jwk header, got nil")

     

       692
       692
       +
       	}

     

       693
       693
       +
       	if err != nil && !contains(err.Error(), "missing jwk") {

     

       694
       694
       +
       		t.Errorf("Expected missing jwk error, got: %v", err)

     

       695
       695
       +
       	}

     

       696
       696
       +
       }

     

       697
       697
       +
       

     

       698
       698
       +
       func TestVerifyDPoPProof_CustomTimeSettings(t *testing.T) {

     

       699
       699
       +
       	verifier := &DPoPVerifier{

     

       700
       700
       +
       		MaxClockSkew: 1 * time.Minute,

     

       701
       701
       +
       		MaxProofAge:  10 * time.Minute,

     

       702
       702
       +
       	}

     

       703
       703
       +
       	key := generateTestES256Key(t)

     

       704
       704
       +
       

     

       705
       705
       +
       	method := "POST"

     

       706
       706
       +
       	uri := "https://api.example.com/resource"

     

       707
       707
       +
       	// Proof issued 50 seconds in the future (within custom MaxClockSkew)

     

       708
       708
       +
       	iat := time.Now().Add(50 * time.Second)

     

       709
       709
       +
       	jti := uuid.New().String()

     

       710
       710
       +
       

     

       711
       711
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       712
       712
       +
       

     

       713
       713
       +
       	_, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       714
       714
       +
       	if err != nil {

     

       715
       715
       +
       		t.Fatalf("VerifyDPoPProof failed with custom time settings: %v", err)

     

       716
       716
       +
       	}

     

       717
       717
       +
       }

     

       718
       718
       +
       

     

       719
       719
       +
       func TestVerifyDPoPProof_HTTPMethodCaseInsensitive(t *testing.T) {

     

       720
       720
       +
       	// HTTP method comparison should be case-insensitive per spec

     

       721
       721
       +
       	verifier := NewDPoPVerifier()

     

       722
       722
       +
       	key := generateTestES256Key(t)

     

       723
       723
       +
       

     

       724
       724
       +
       	method := "post"

     

       725
       725
       +
       	uri := "https://api.example.com/resource"

     

       726
       726
       +
       	iat := time.Now()

     

       727
       727
       +
       	jti := uuid.New().String()

     

       728
       728
       +
       

     

       729
       729
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       730
       730
       +
       

     

       731
       731
       +
       	// Verify with uppercase method

     

       732
       732
       +
       	_, err := verifier.VerifyDPoPProof(proof, "POST", uri)

     

       733
       733
       +
       	if err != nil {

     

       734
       734
       +
       		t.Fatalf("VerifyDPoPProof failed for case-insensitive method: %v", err)

     

       735
       735
       +
       	}

     

       736
       736
       +
       }

     

       737
       737
       +
       

     

       738
       738
       +
       // === Token Binding Verification Tests ===

     

       739
       739
       +
       

     

       740
       740
       +
       func TestVerifyTokenBinding_Matching(t *testing.T) {

     

       741
       741
       +
       	verifier := NewDPoPVerifier()

     

       742
       742
       +
       	key := generateTestES256Key(t)

     

       743
       743
       +
       

     

       744
       744
       +
       	method := "POST"

     

       745
       745
       +
       	uri := "https://api.example.com/resource"

     

       746
       746
       +
       	iat := time.Now()

     

       747
       747
       +
       	jti := uuid.New().String()

     

       748
       748
       +
       

     

       749
       749
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       750
       750
       +
       

     

       751
       751
       +
       	result, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       752
       752
       +
       	if err != nil {

     

       753
       753
       +
       		t.Fatalf("VerifyDPoPProof failed: %v", err)

     

       754
       754
       +
       	}

     

       755
       755
       +
       

     

       756
       756
       +
       	// Verify token binding with matching thumbprint

     

       757
       757
       +
       	err = verifier.VerifyTokenBinding(result, key.thumbprint)

     

       758
       758
       +
       	if err != nil {

     

       759
       759
       +
       		t.Fatalf("VerifyTokenBinding failed for matching thumbprint: %v", err)

     

       760
       760
       +
       	}

     

       761
       761
       +
       }

     

       762
       762
       +
       

     

       763
       763
       +
       func TestVerifyTokenBinding_Mismatch(t *testing.T) {

     

       764
       764
       +
       	verifier := NewDPoPVerifier()

     

       765
       765
       +
       	key := generateTestES256Key(t)

     

       766
       766
       +
       	wrongKey := generateTestES256Key(t)

     

       767
       767
       +
       

     

       768
       768
       +
       	method := "POST"

     

       769
       769
       +
       	uri := "https://api.example.com/resource"

     

       770
       770
       +
       	iat := time.Now()

     

       771
       771
       +
       	jti := uuid.New().String()

     

       772
       772
       +
       

     

       773
       773
       +
       	proof := createDPoPProof(t, key, method, uri, iat, jti)

     

       774
       774
       +
       

     

       775
       775
       +
       	result, err := verifier.VerifyDPoPProof(proof, method, uri)

     

       776
       776
       +
       	if err != nil {

     

       777
       777
       +
       		t.Fatalf("VerifyDPoPProof failed: %v", err)

     

       778
       778
       +
       	}

     

       779
       779
       +
       

     

       780
       780
       +
       	// Verify token binding with wrong thumbprint

     

       781
       781
       +
       	err = verifier.VerifyTokenBinding(result, wrongKey.thumbprint)

     

       782
       782
       +
       	if err == nil {

     

       783
       783
       +
       		t.Error("Expected error for thumbprint mismatch, got nil")

     

       784
       784
       +
       	}

     

       785
       785
       +
       	if err != nil && !contains(err.Error(), "thumbprint mismatch") {

     

       786
       786
       +
       		t.Errorf("Expected thumbprint mismatch error, got: %v", err)

     

       787
       787
       +
       	}

     

       788
       788
       +
       }

     

       789
       789
       +
       

     

       790
       790
       +
       // === ExtractCnfJkt Tests ===

     

       791
       791
       +
       

     

       792
       792
       +
       func TestExtractCnfJkt_Valid(t *testing.T) {

     

       793
       793
       +
       	expectedJkt := "test-thumbprint-123"

     

       794
       794
       +
       	claims := &Claims{

     

       795
       795
       +
       		Confirmation: map[string]interface{}{

     

       796
       796
       +
       			"jkt": expectedJkt,

     

       797
       797
       +
       		},

     

       798
       798
       +
       	}

     

       799
       799
       +
       

     

       800
       800
       +
       	jkt, err := ExtractCnfJkt(claims)

     

       801
       801
       +
       	if err != nil {

     

       802
       802
       +
       		t.Fatalf("ExtractCnfJkt failed for valid claims: %v", err)

     

       803
       803
       +
       	}

     

       804
       804
       +
       

     

       805
       805
       +
       	if jkt != expectedJkt {

     

       806
       806
       +
       		t.Errorf("Expected jkt %s, got %s", expectedJkt, jkt)

     

       807
       807
       +
       	}

     

       808
       808
       +
       }

     

       809
       809
       +
       

     

       810
       810
       +
       func TestExtractCnfJkt_MissingCnf(t *testing.T) {

     

       811
       811
       +
       	claims := &Claims{

     

       812
       812
       +
       		// No Confirmation

     

       813
       813
       +
       	}

     

       814
       814
       +
       

     

       815
       815
       +
       	_, err := ExtractCnfJkt(claims)

     

       816
       816
       +
       	if err == nil {

     

       817
       817
       +
       		t.Error("Expected error for missing cnf, got nil")

     

       818
       818
       +
       	}

     

       819
       819
       +
       	if err != nil && !contains(err.Error(), "missing cnf claim") {

     

       820
       820
       +
       		t.Errorf("Expected missing cnf error, got: %v", err)

     

       821
       821
       +
       	}

     

       822
       822
       +
       }

     

       823
       823
       +
       

     

       824
       824
       +
       func TestExtractCnfJkt_NilCnf(t *testing.T) {

     

       825
       825
       +
       	claims := &Claims{

     

       826
       826
       +
       		Confirmation: nil,

     

       827
       827
       +
       	}

     

       828
       828
       +
       

     

       829
       829
       +
       	_, err := ExtractCnfJkt(claims)

     

       830
       830
       +
       	if err == nil {

     

       831
       831
       +
       		t.Error("Expected error for nil cnf, got nil")

     

       832
       832
       +
       	}

     

       833
       833
       +
       	if err != nil && !contains(err.Error(), "missing cnf claim") {

     

       834
       834
       +
       		t.Errorf("Expected missing cnf error, got: %v", err)

     

       835
       835
       +
       	}

     

       836
       836
       +
       }

     

       837
       837
       +
       

     

       838
       838
       +
       func TestExtractCnfJkt_MissingJkt(t *testing.T) {

     

       839
       839
       +
       	claims := &Claims{

     

       840
       840
       +
       		Confirmation: map[string]interface{}{

     

       841
       841
       +
       			"other": "value",

     

       842
       842
       +
       		},

     

       843
       843
       +
       	}

     

       844
       844
       +
       

     

       845
       845
       +
       	_, err := ExtractCnfJkt(claims)

     

       846
       846
       +
       	if err == nil {

     

       847
       847
       +
       		t.Error("Expected error for missing jkt, got nil")

     

       848
       848
       +
       	}

     

       849
       849
       +
       	if err != nil && !contains(err.Error(), "missing jkt") {

     

       850
       850
       +
       		t.Errorf("Expected missing jkt error, got: %v", err)

     

       851
       851
       +
       	}

     

       852
       852
       +
       }

     

       853
       853
       +
       

     

       854
       854
       +
       func TestExtractCnfJkt_EmptyJkt(t *testing.T) {

     

       855
       855
       +
       	claims := &Claims{

     

       856
       856
       +
       		Confirmation: map[string]interface{}{

     

       857
       857
       +
       			"jkt": "",

     

       858
       858
       +
       		},

     

       859
       859
       +
       	}

     

       860
       860
       +
       

     

       861
       861
       +
       	_, err := ExtractCnfJkt(claims)

     

       862
       862
       +
       	if err == nil {

     

       863
       863
       +
       		t.Error("Expected error for empty jkt, got nil")

     

       864
       864
       +
       	}

     

       865
       865
       +
       	if err != nil && !contains(err.Error(), "missing jkt") {

     

       866
       866
       +
       		t.Errorf("Expected missing jkt error, got: %v", err)

     

       867
       867
       +
       	}

     

       868
       868
       +
       }

     

       869
       869
       +
       

     

       870
       870
       +
       func TestExtractCnfJkt_WrongType(t *testing.T) {

     

       871
       871
       +
       	claims := &Claims{

     

       872
       872
       +
       		Confirmation: map[string]interface{}{

     

       873
       873
       +
       			"jkt": 123, // Not a string

     

       874
       874
       +
       		},

     

       875
       875
       +
       	}

     

       876
       876
       +
       

     

       877
       877
       +
       	_, err := ExtractCnfJkt(claims)

     

       878
       878
       +
       	if err == nil {

     

       879
       879
       +
       		t.Error("Expected error for wrong type jkt, got nil")

     

       880
       880
       +
       	}

     

       881
       881
       +
       	if err != nil && !contains(err.Error(), "missing jkt") {

     

       882
       882
       +
       		t.Errorf("Expected missing jkt error, got: %v", err)

     

       883
       883
       +
       	}

     

       884
       884
       +
       }

     

       885
       885
       +
       

     

       886
       886
       +
       // === Helper Functions for Tests ===

     

       887
       887
       +
       

     

       888
       888
       +
       // splitJWT splits a JWT into its three parts

     

       889
       889
       +
       func splitJWT(token string) []string {

     

       890
       890
       +
       	return []string{

     

       891
       891
       +
       		token[:strings.IndexByte(token, '.')],

     

       892
       892
       +
       		token[strings.IndexByte(token, '.')+1 : strings.LastIndexByte(token, '.')],

     

       893
       893
       +
       		token[strings.LastIndexByte(token, '.')+1:],

     

       894
       894
       +
       	}

     

       895
       895
       +
       }

     

       896
       896
       +
       

     

       897
       897
       +
       // parseJWTHeader parses a base64url-encoded JWT header

     

       898
       898
       +
       func parseJWTHeader(t *testing.T, encoded string) map[string]interface{} {

     

       899
       899
       +
       	t.Helper()

     

       900
       900
       +
       	decoded, err := base64.RawURLEncoding.DecodeString(encoded)

     

       901
       901
       +
       	if err != nil {

     

       902
       902
       +
       		t.Fatalf("Failed to decode header: %v", err)

     

       903
       903
       +
       	}

     

       904
       904
       +
       

     

       905
       905
       +
       	var header map[string]interface{}

     

       906
       906
       +
       	if err := json.Unmarshal(decoded, &header); err != nil {

     

       907
       907
       +
       		t.Fatalf("Failed to unmarshal header: %v", err)

     

       908
       908
       +
       	}

     

       909
       909
       +
       

     

       910
       910
       +
       	return header

     

       911
       911
       +
       }

     

       912
       912
       +
       

     

       913
       913
       +
       // encodeJSON encodes a value to base64url-encoded JSON

     

       914
       914
       +
       func encodeJSON(t *testing.T, v interface{}) string {

     

       915
       915
       +
       	t.Helper()

     

       916
       916
       +
       	data, err := json.Marshal(v)

     

       917
       917
       +
       	if err != nil {

     

       918
       918
       +
       		t.Fatalf("Failed to marshal JSON: %v", err)

     

       919
       919
       +
       	}

     

       920
       920
       +
       	return base64.RawURLEncoding.EncodeToString(data)

     

       921
       921
       +
       }

+148 -6

internal/api/middleware/auth.go

···

       3
       3
        
       import (

     

       4
       4
        
       	"Coves/internal/atproto/auth"

     

       5
       5
        
       	"context"

     

       6
       6
       +
       	"fmt"

     

       6
       7
        
       	"log"

     

       7
       8
        
       	"net/http"

     

       8
       9
        
       	"strings"

     
···

       15
       16
        
       	UserDIDKey      contextKey = "user_did"

     

       16
       17
        
       	JWTClaimsKey    contextKey = "jwt_claims"

     

       17
       18
        
       	UserAccessToken contextKey = "user_access_token"

     

       19
       19
       +
       	DPoPProofKey    contextKey = "dpop_proof"

     

       18
       20
        
       )

     

       19
       21
        
       

     

       20
       22
        
       // AtProtoAuthMiddleware enforces atProto OAuth authentication for protected routes

     

       21
       23
        
       // Validates JWT Bearer tokens from the Authorization header

     

       24
       24
       +
       // Supports DPoP (RFC 9449) for token binding verification

     

       22
       25
        
       type AtProtoAuthMiddleware struct {

     

       23
       23
       -
       	jwksFetcher auth.JWKSFetcher

     

       24
       24
       -
       	skipVerify  bool // For Phase 1 testing only

     

       26
       26
       +
       	jwksFetcher  auth.JWKSFetcher

     

       27
       27
       +
       	dpopVerifier *auth.DPoPVerifier

     

       28
       28
       +
       	skipVerify   bool // For Phase 1 testing only

     

       25
       29
        
       }

     

       26
       30
        
       

     

       27
       31
        
       // NewAtProtoAuthMiddleware creates a new atProto auth middleware

     

       28
       32
        
       // skipVerify: if true, only parses JWT without signature verification (Phase 1)

     

       29
       33
        
       //

     

       30
       34
        
       //	if false, performs full signature verification (Phase 2)

     

       35
       35
       +
       //

     

       36
       36
       +
       // IMPORTANT: Call Stop() when shutting down to clean up background goroutines.

     

       31
       37
        
       func NewAtProtoAuthMiddleware(jwksFetcher auth.JWKSFetcher, skipVerify bool) *AtProtoAuthMiddleware {

     

       32
       38
        
       	return &AtProtoAuthMiddleware{

     

       33
       33
       -
       		jwksFetcher: jwksFetcher,

     

       34
       34
       -
       		skipVerify:  skipVerify,

     

       39
       39
       +
       		jwksFetcher:  jwksFetcher,

     

       40
       40
       +
       		dpopVerifier: auth.NewDPoPVerifier(),

     

       41
       41
       +
       		skipVerify:   skipVerify,

     

       42
       42
       +
       	}

     

       43
       43
       +
       }

     

       44
       44
       +
       

     

       45
       45
       +
       // Stop stops background goroutines. Call this when shutting down the server.

     

       46
       46
       +
       // This prevents goroutine leaks from the DPoP verifier's replay protection cache.

     

       47
       47
       +
       func (m *AtProtoAuthMiddleware) Stop() {

     

       48
       48
       +
       	if m.dpopVerifier != nil {

     

       49
       49
       +
       		m.dpopVerifier.Stop()

     

       35
       50
        
       	}

     

       36
       51
        
       }

     

       37
       52
        
       

     
···

       70
       85
        
       			}

     

       71
       86
        
       		} else {

     

       72
       87
        
       			// Phase 2: Full verification with signature check

     

       88
       88
       +
       			//

     

       89
       89
       +
       			// SECURITY: The access token MUST be verified before trusting any claims.

     

       90
       90
       +
       			// DPoP is an ADDITIONAL security layer, not a replacement for signature verification.

     

       73
       91
        
       			claims, err = auth.VerifyJWT(r.Context(), token, m.jwksFetcher)

     

       74
       92
        
       			if err != nil {

     

       75
       75
       -
       				// Try to extract issuer for better logging

     

       93
       93
       +
       				// Token verification failed - REJECT

     

       94
       94
       +
       				// DO NOT fall back to DPoP-only verification, as that would trust unverified claims

     

       76
       95
        
       				issuer := "unknown"

     

       77
       96
        
       				if parsedClaims, parseErr := auth.ParseJWT(token); parseErr == nil {

     

       78
       97
        
       					issuer = parsedClaims.Issuer

     
···

       82
       101
        
       				writeAuthError(w, "Invalid or expired token")

     

       83
       102
        
       				return

     

       84
       103
        
       			}

     

       104
       104
       +
       

     

       105
       105
       +
       			// Token signature verified - now check if DPoP binding is required

     

       106
       106
       +
       			// If the token has a cnf.jkt claim, DPoP proof is REQUIRED

     

       107
       107
       +
       			dpopHeader := r.Header.Get("DPoP")

     

       108
       108
       +
       			hasCnfJkt := claims.Confirmation != nil && claims.Confirmation["jkt"] != nil

     

       109
       109
       +
       

     

       110
       110
       +
       			if hasCnfJkt {

     

       111
       111
       +
       				// Token has DPoP binding - REQUIRE valid DPoP proof

     

       112
       112
       +
       				if dpopHeader == "" {

     

       113
       113
       +
       					log.Printf("[AUTH_FAILURE] type=missing_dpop ip=%s method=%s path=%s error=token has cnf.jkt but no DPoP header",

     

       114
       114
       +
       						r.RemoteAddr, r.Method, r.URL.Path)

     

       115
       115
       +
       					writeAuthError(w, "DPoP proof required")

     

       116
       116
       +
       					return

     

       117
       117
       +
       				}

     

       118
       118
       +
       

     

       119
       119
       +
       				proof, err := m.verifyDPoPBinding(r, claims, dpopHeader)

     

       120
       120
       +
       				if err != nil {

     

       121
       121
       +
       					log.Printf("[AUTH_FAILURE] type=dpop_verification_failed ip=%s method=%s path=%s error=%v",

     

       122
       122
       +
       						r.RemoteAddr, r.Method, r.URL.Path, err)

     

       123
       123
       +
       					writeAuthError(w, "Invalid DPoP proof")

     

       124
       124
       +
       					return

     

       125
       125
       +
       				}

     

       126
       126
       +
       

     

       127
       127
       +
       				// Store verified DPoP proof in context

     

       128
       128
       +
       				ctx := context.WithValue(r.Context(), DPoPProofKey, proof)

     

       129
       129
       +
       				r = r.WithContext(ctx)

     

       130
       130
       +
       			} else if dpopHeader != "" {

     

       131
       131
       +
       				// DPoP header present but token doesn't have cnf.jkt - this is suspicious

     

       132
       132
       +
       				// Log warning but don't reject (could be a misconfigured client)

     

       133
       133
       +
       				log.Printf("[AUTH_WARNING] type=unexpected_dpop ip=%s method=%s path=%s warning=DPoP header present but token has no cnf.jkt",

     

       134
       134
       +
       					r.RemoteAddr, r.Method, r.URL.Path)

     

       135
       135
       +
       			}

     

       85
       136
        
       		}

     

       86
       137
        
       

     

       87
       138
        
       		// Extract user DID from 'sub' claim

     
···

       124
       175
        
       			claims, err = auth.ParseJWT(token)

     

       125
       176
        
       		} else {

     

       126
       177
        
       			// Phase 2: Full verification

     

       178
       178
       +
       			// SECURITY: Token MUST be verified before trusting claims

     

       127
       179
        
       			claims, err = auth.VerifyJWT(r.Context(), token, m.jwksFetcher)

     

       128
       180
        
       		}

     

       129
       181
        
       

     
···

       134
       186
        
       			return

     

       135
       187
        
       		}

     

       136
       188
        
       

     

       137
       137
       -
       		// Inject user info and access token into context

     

       189
       189
       +
       		// Check DPoP binding if token has cnf.jkt (after successful verification)

     

       190
       190
       +
       		// SECURITY: If token has cnf.jkt but no DPoP header, we cannot trust it

     

       191
       191
       +
       		// (could be a stolen token). Continue as unauthenticated.

     

       192
       192
       +
       		if !m.skipVerify {

     

       193
       193
       +
       			dpopHeader := r.Header.Get("DPoP")

     

       194
       194
       +
       			hasCnfJkt := claims.Confirmation != nil && claims.Confirmation["jkt"] != nil

     

       195
       195
       +
       

     

       196
       196
       +
       			if hasCnfJkt {

     

       197
       197
       +
       				if dpopHeader == "" {

     

       198
       198
       +
       					// Token requires DPoP binding but no proof provided

     

       199
       199
       +
       					// Cannot trust this token - continue without auth

     

       200
       200
       +
       					log.Printf("[AUTH_WARNING] Optional auth: token has cnf.jkt but no DPoP header - treating as unauthenticated (potential token theft)")

     

       201
       201
       +
       					next.ServeHTTP(w, r)

     

       202
       202
       +
       					return

     

       203
       203
       +
       				}

     

       204
       204
       +
       

     

       205
       205
       +
       				proof, err := m.verifyDPoPBinding(r, claims, dpopHeader)

     

       206
       206
       +
       				if err != nil {

     

       207
       207
       +
       					// DPoP verification failed - cannot trust this token

     

       208
       208
       +
       					log.Printf("[AUTH_WARNING] Optional auth: DPoP verification failed - treating as unauthenticated: %v", err)

     

       209
       209
       +
       					next.ServeHTTP(w, r)

     

       210
       210
       +
       					return

     

       211
       211
       +
       				}

     

       212
       212
       +
       

     

       213
       213
       +
       				// DPoP verified - inject proof into context

     

       214
       214
       +
       				ctx := context.WithValue(r.Context(), UserDIDKey, claims.Subject)

     

       215
       215
       +
       				ctx = context.WithValue(ctx, JWTClaimsKey, claims)

     

       216
       216
       +
       				ctx = context.WithValue(ctx, UserAccessToken, token)

     

       217
       217
       +
       				ctx = context.WithValue(ctx, DPoPProofKey, proof)

     

       218
       218
       +
       				next.ServeHTTP(w, r.WithContext(ctx))

     

       219
       219
       +
       				return

     

       220
       220
       +
       			}

     

       221
       221
       +
       		}

     

       222
       222
       +
       

     

       223
       223
       +
       		// No DPoP binding required - inject user info and access token into context

     

       138
       224
        
       		ctx := context.WithValue(r.Context(), UserDIDKey, claims.Subject)

     

       139
       225
        
       		ctx = context.WithValue(ctx, JWTClaimsKey, claims)

     

       140
       226
        
       		ctx = context.WithValue(ctx, UserAccessToken, token)

     
···

       179
       265
        
       	return token

     

       180
       266
        
       }

     

       181
       267
        
       

     

       268
       268
       +
       // GetDPoPProof extracts the DPoP proof from the request context

     

       269
       269
       +
       // Returns nil if no DPoP proof was verified

     

       270
       270
       +
       func GetDPoPProof(r *http.Request) *auth.DPoPProof {

     

       271
       271
       +
       	proof, _ := r.Context().Value(DPoPProofKey).(*auth.DPoPProof)

     

       272
       272
       +
       	return proof

     

       273
       273
       +
       }

     

       274
       274
       +
       

     

       275
       275
       +
       // verifyDPoPBinding verifies DPoP proof binding for an ALREADY VERIFIED token.

     

       276
       276
       +
       //

     

       277
       277
       +
       // SECURITY: This function ONLY verifies the DPoP proof and its binding to the token.

     

       278
       278
       +
       // The access token MUST be signature-verified BEFORE calling this function.

     

       279
       279
       +
       // DPoP is an ADDITIONAL security layer, not a replacement for signature verification.

     

       280
       280
       +
       //

     

       281
       281
       +
       // This prevents token theft attacks by proving the client possesses the private key

     

       282
       282
       +
       // corresponding to the public key thumbprint in the token's cnf.jkt claim.

     

       283
       283
       +
       func (m *AtProtoAuthMiddleware) verifyDPoPBinding(r *http.Request, claims *auth.Claims, dpopProofHeader string) (*auth.DPoPProof, error) {

     

       284
       284
       +
       	// Extract the cnf.jkt claim from the already-verified token

     

       285
       285
       +
       	jkt, err := auth.ExtractCnfJkt(claims)

     

       286
       286
       +
       	if err != nil {

     

       287
       287
       +
       		return nil, fmt.Errorf("token requires DPoP but missing cnf.jkt: %w", err)

     

       288
       288
       +
       	}

     

       289
       289
       +
       

     

       290
       290
       +
       	// Build the HTTP URI for DPoP verification

     

       291
       291
       +
       	// Use the full URL including scheme and host

     

       292
       292
       +
       	scheme := strings.TrimSpace(r.URL.Scheme)

     

       293
       293
       +
       	if forwardedProto := r.Header.Get("X-Forwarded-Proto"); forwardedProto != "" {

     

       294
       294
       +
       		// Forwarded proto may contain a comma-separated list; use the first entry

     

       295
       295
       +
       		parts := strings.Split(forwardedProto, ",")

     

       296
       296
       +
       		if len(parts) > 0 && strings.TrimSpace(parts[0]) != "" {

     

       297
       297
       +
       			scheme = strings.ToLower(strings.TrimSpace(parts[0]))

     

       298
       298
       +
       		}

     

       299
       299
       +
       	}

     

       300
       300
       +
       	if scheme == "" {

     

       301
       301
       +
       		if r.TLS != nil {

     

       302
       302
       +
       			scheme = "https"

     

       303
       303
       +
       		} else {

     

       304
       304
       +
       			scheme = "http"

     

       305
       305
       +
       		}

     

       306
       306
       +
       	}

     

       307
       307
       +
       	scheme = strings.ToLower(scheme)

     

       308
       308
       +
       	httpURI := scheme + "://" + r.Host + r.URL.Path

     

       309
       309
       +
       

     

       310
       310
       +
       	// Verify the DPoP proof

     

       311
       311
       +
       	proof, err := m.dpopVerifier.VerifyDPoPProof(dpopProofHeader, r.Method, httpURI)

     

       312
       312
       +
       	if err != nil {

     

       313
       313
       +
       		return nil, fmt.Errorf("DPoP proof verification failed: %w", err)

     

       314
       314
       +
       	}

     

       315
       315
       +
       

     

       316
       316
       +
       	// Verify the binding between the proof and the token

     

       317
       317
       +
       	if err := m.dpopVerifier.VerifyTokenBinding(proof, jkt); err != nil {

     

       318
       318
       +
       		return nil, fmt.Errorf("DPoP binding verification failed: %w", err)

     

       319
       319
       +
       	}

     

       320
       320
       +
       

     

       321
       321
       +
       	return proof, nil

     

       322
       322
       +
       }

     

       323
       323
       +
       

     

       182
       324
        
       // writeAuthError writes a JSON error response for authentication failures

     

       183
       325
        
       func writeAuthError(w http.ResponseWriter, message string) {

     

       184
       326
        
       	w.Header().Set("Content-Type", "application/json")

+416

internal/api/middleware/auth_test.go

···

       1
       1
        
       package middleware

     

       2
       2
        
       

     

       3
       3
        
       import (

     

       4
       4
       +
       	"Coves/internal/atproto/auth"

     

       4
       5
        
       	"context"

     

       6
       6
       +
       	"crypto/ecdsa"

     

       7
       7
       +
       	"crypto/elliptic"

     

       8
       8
       +
       	"crypto/rand"

     

       9
       9
       +
       	"encoding/base64"

     

       5
       10
        
       	"fmt"

     

       6
       11
        
       	"net/http"

     

       7
       12
        
       	"net/http/httptest"

     
···

       9
       14
        
       	"time"

     

       10
       15
        
       

     

       11
       16
        
       	"github.com/golang-jwt/jwt/v5"

     

       17
       17
       +
       	"github.com/google/uuid"

     

       12
       18
        
       )

     

       13
       19
        
       

     

       14
       20
        
       // mockJWKSFetcher is a test double for JWKSFetcher

     
···

       326
       332
        
       		t.Errorf("expected nil claims, got %+v", claims)

     

       327
       333
        
       	}

     

       328
       334
        
       }

     

       335
       335
       +
       

     

       336
       336
       +
       // TestGetDPoPProof_NotAuthenticated tests that GetDPoPProof returns nil when no DPoP was verified

     

       337
       337
       +
       func TestGetDPoPProof_NotAuthenticated(t *testing.T) {

     

       338
       338
       +
       	req := httptest.NewRequest("GET", "/test", nil)

     

       339
       339
       +
       	proof := GetDPoPProof(req)

     

       340
       340
       +
       

     

       341
       341
       +
       	if proof != nil {

     

       342
       342
       +
       		t.Errorf("expected nil proof, got %+v", proof)

     

       343
       343
       +
       	}

     

       344
       344
       +
       }

     

       345
       345
       +
       

     

       346
       346
       +
       // TestRequireAuth_WithDPoP_SecurityModel tests the correct DPoP security model:

     

       347
       347
       +
       // Token MUST be verified first, then DPoP is checked as an additional layer.

     

       348
       348
       +
       // DPoP is NOT a fallback for failed token verification.

     

       349
       349
       +
       func TestRequireAuth_WithDPoP_SecurityModel(t *testing.T) {

     

       350
       350
       +
       	// Generate an ECDSA key pair for DPoP

     

       351
       351
       +
       	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

     

       352
       352
       +
       	if err != nil {

     

       353
       353
       +
       		t.Fatalf("failed to generate key: %v", err)

     

       354
       354
       +
       	}

     

       355
       355
       +
       

     

       356
       356
       +
       	// Calculate JWK thumbprint for cnf.jkt

     

       357
       357
       +
       	jwk := ecdsaPublicKeyToJWK(&privateKey.PublicKey)

     

       358
       358
       +
       	thumbprint, err := auth.CalculateJWKThumbprint(jwk)

     

       359
       359
       +
       	if err != nil {

     

       360
       360
       +
       		t.Fatalf("failed to calculate thumbprint: %v", err)

     

       361
       361
       +
       	}

     

       362
       362
       +
       

     

       363
       363
       +
       	t.Run("DPoP_is_NOT_fallback_for_failed_verification", func(t *testing.T) {

     

       364
       364
       +
       		// SECURITY TEST: When token verification fails, DPoP should NOT be used as fallback

     

       365
       365
       +
       		// This prevents an attacker from forging a token with their own cnf.jkt

     

       366
       366
       +
       

     

       367
       367
       +
       		// Create a DPoP-bound access token (unsigned - will fail verification)

     

       368
       368
       +
       		claims := auth.Claims{

     

       369
       369
       +
       			RegisteredClaims: jwt.RegisteredClaims{

     

       370
       370
       +
       				Subject:   "did:plc:attacker",

     

       371
       371
       +
       				Issuer:    "https://external.pds.local",

     

       372
       372
       +
       				ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),

     

       373
       373
       +
       				IssuedAt:  jwt.NewNumericDate(time.Now()),

     

       374
       374
       +
       			},

     

       375
       375
       +
       			Scope: "atproto",

     

       376
       376
       +
       			Confirmation: map[string]interface{}{

     

       377
       377
       +
       				"jkt": thumbprint,

     

       378
       378
       +
       			},

     

       379
       379
       +
       		}

     

       380
       380
       +
       

     

       381
       381
       +
       		token := jwt.NewWithClaims(jwt.SigningMethodNone, claims)

     

       382
       382
       +
       		tokenString, _ := token.SignedString(jwt.UnsafeAllowNoneSignatureType)

     

       383
       383
       +
       

     

       384
       384
       +
       		// Create valid DPoP proof (attacker has the private key)

     

       385
       385
       +
       		dpopProof := createDPoPProof(t, privateKey, "GET", "https://test.local/api/endpoint")

     

       386
       386
       +
       

     

       387
       387
       +
       		// Mock fetcher that fails (simulating external PDS without JWKS)

     

       388
       388
       +
       		fetcher := &mockJWKSFetcher{shouldFail: true}

     

       389
       389
       +
       		middleware := NewAtProtoAuthMiddleware(fetcher, false) // skipVerify=false

     

       390
       390
       +
       

     

       391
       391
       +
       		handler := middleware.RequireAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

     

       392
       392
       +
       			t.Error("SECURITY VULNERABILITY: handler was called despite token verification failure")

     

       393
       393
       +
       		}))

     

       394
       394
       +
       

     

       395
       395
       +
       		req := httptest.NewRequest("GET", "https://test.local/api/endpoint", nil)

     

       396
       396
       +
       		req.Header.Set("Authorization", "Bearer "+tokenString)

     

       397
       397
       +
       		req.Header.Set("DPoP", dpopProof)

     

       398
       398
       +
       		w := httptest.NewRecorder()

     

       399
       399
       +
       

     

       400
       400
       +
       		handler.ServeHTTP(w, req)

     

       401
       401
       +
       

     

       402
       402
       +
       		// MUST reject - token verification failed, DPoP cannot substitute for signature verification

     

       403
       403
       +
       		if w.Code != http.StatusUnauthorized {

     

       404
       404
       +
       			t.Errorf("SECURITY: expected 401 for unverified token, got %d", w.Code)

     

       405
       405
       +
       		}

     

       406
       406
       +
       	})

     

       407
       407
       +
       

     

       408
       408
       +
       	t.Run("DPoP_required_when_cnf_jkt_present_in_verified_token", func(t *testing.T) {

     

       409
       409
       +
       		// When token has cnf.jkt, DPoP header MUST be present

     

       410
       410
       +
       		// This test uses skipVerify=true to simulate a verified token

     

       411
       411
       +
       

     

       412
       412
       +
       		claims := auth.Claims{

     

       413
       413
       +
       			RegisteredClaims: jwt.RegisteredClaims{

     

       414
       414
       +
       				Subject:   "did:plc:test123",

     

       415
       415
       +
       				Issuer:    "https://test.pds.local",

     

       416
       416
       +
       				ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),

     

       417
       417
       +
       				IssuedAt:  jwt.NewNumericDate(time.Now()),

     

       418
       418
       +
       			},

     

       419
       419
       +
       			Scope: "atproto",

     

       420
       420
       +
       			Confirmation: map[string]interface{}{

     

       421
       421
       +
       				"jkt": thumbprint,

     

       422
       422
       +
       			},

     

       423
       423
       +
       		}

     

       424
       424
       +
       

     

       425
       425
       +
       		token := jwt.NewWithClaims(jwt.SigningMethodNone, claims)

     

       426
       426
       +
       		tokenString, _ := token.SignedString(jwt.UnsafeAllowNoneSignatureType)

     

       427
       427
       +
       

     

       428
       428
       +
       		// NO DPoP header - should fail when skipVerify is false

     

       429
       429
       +
       		// Note: with skipVerify=true, DPoP is not checked

     

       430
       430
       +
       		fetcher := &mockJWKSFetcher{}

     

       431
       431
       +
       		middleware := NewAtProtoAuthMiddleware(fetcher, true) // skipVerify=true for parsing

     

       432
       432
       +
       

     

       433
       433
       +
       		handlerCalled := false

     

       434
       434
       +
       		handler := middleware.RequireAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

     

       435
       435
       +
       			handlerCalled = true

     

       436
       436
       +
       			w.WriteHeader(http.StatusOK)

     

       437
       437
       +
       		}))

     

       438
       438
       +
       

     

       439
       439
       +
       		req := httptest.NewRequest("GET", "https://test.local/api/endpoint", nil)

     

       440
       440
       +
       		req.Header.Set("Authorization", "Bearer "+tokenString)

     

       441
       441
       +
       		// No DPoP header

     

       442
       442
       +
       		w := httptest.NewRecorder()

     

       443
       443
       +
       

     

       444
       444
       +
       		handler.ServeHTTP(w, req)

     

       445
       445
       +
       

     

       446
       446
       +
       		// With skipVerify=true, DPoP is not checked, so this should succeed

     

       447
       447
       +
       		if !handlerCalled {

     

       448
       448
       +
       			t.Error("handler should be called when skipVerify=true")

     

       449
       449
       +
       		}

     

       450
       450
       +
       	})

     

       451
       451
       +
       }

     

       452
       452
       +
       

     

       453
       453
       +
       // TestRequireAuth_TokenVerificationFails_DPoPNotUsedAsFallback is the key security test.

     

       454
       454
       +
       // It ensures that DPoP cannot be used as a fallback when token signature verification fails.

     

       455
       455
       +
       func TestRequireAuth_TokenVerificationFails_DPoPNotUsedAsFallback(t *testing.T) {

     

       456
       456
       +
       	// Generate a key pair (attacker's key)

     

       457
       457
       +
       	attackerKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

     

       458
       458
       +
       	jwk := ecdsaPublicKeyToJWK(&attackerKey.PublicKey)

     

       459
       459
       +
       	thumbprint, _ := auth.CalculateJWKThumbprint(jwk)

     

       460
       460
       +
       

     

       461
       461
       +
       	// Create a FORGED token claiming to be the victim

     

       462
       462
       +
       	claims := auth.Claims{

     

       463
       463
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       464
       464
       +
       			Subject:   "did:plc:victim_user", // Attacker claims to be victim

     

       465
       465
       +
       			Issuer:    "https://untrusted.pds",

     

       466
       466
       +
       			ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),

     

       467
       467
       +
       			IssuedAt:  jwt.NewNumericDate(time.Now()),

     

       468
       468
       +
       		},

     

       469
       469
       +
       		Scope: "atproto",

     

       470
       470
       +
       		Confirmation: map[string]interface{}{

     

       471
       471
       +
       			"jkt": thumbprint, // Attacker uses their own key

     

       472
       472
       +
       		},

     

       473
       473
       +
       	}

     

       474
       474
       +
       

     

       475
       475
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodNone, claims)

     

       476
       476
       +
       	tokenString, _ := token.SignedString(jwt.UnsafeAllowNoneSignatureType)

     

       477
       477
       +
       

     

       478
       478
       +
       	// Attacker creates a valid DPoP proof with their key

     

       479
       479
       +
       	dpopProof := createDPoPProof(t, attackerKey, "POST", "https://api.example.com/protected")

     

       480
       480
       +
       

     

       481
       481
       +
       	// Fetcher fails (external PDS without JWKS)

     

       482
       482
       +
       	fetcher := &mockJWKSFetcher{shouldFail: true}

     

       483
       483
       +
       	middleware := NewAtProtoAuthMiddleware(fetcher, false) // skipVerify=false - REAL verification

     

       484
       484
       +
       

     

       485
       485
       +
       	handler := middleware.RequireAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

     

       486
       486
       +
       		t.Fatalf("CRITICAL SECURITY FAILURE: Request authenticated as %s despite forged token!",

     

       487
       487
       +
       			GetUserDID(r))

     

       488
       488
       +
       	}))

     

       489
       489
       +
       

     

       490
       490
       +
       	req := httptest.NewRequest("POST", "https://api.example.com/protected", nil)

     

       491
       491
       +
       	req.Header.Set("Authorization", "Bearer "+tokenString)

     

       492
       492
       +
       	req.Header.Set("DPoP", dpopProof)

     

       493
       493
       +
       	w := httptest.NewRecorder()

     

       494
       494
       +
       

     

       495
       495
       +
       	handler.ServeHTTP(w, req)

     

       496
       496
       +
       

     

       497
       497
       +
       	// MUST reject - the token signature was never verified

     

       498
       498
       +
       	if w.Code != http.StatusUnauthorized {

     

       499
       499
       +
       		t.Errorf("SECURITY VULNERABILITY: Expected 401, got %d. Token was not properly verified!", w.Code)

     

       500
       500
       +
       	}

     

       501
       501
       +
       }

     

       502
       502
       +
       

     

       503
       503
       +
       // TestVerifyDPoPBinding_UsesForwardedProto ensures we honor the external HTTPS

     

       504
       504
       +
       // scheme when TLS is terminated upstream and X-Forwarded-Proto is present.

     

       505
       505
       +
       func TestVerifyDPoPBinding_UsesForwardedProto(t *testing.T) {

     

       506
       506
       +
       	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

     

       507
       507
       +
       	if err != nil {

     

       508
       508
       +
       		t.Fatalf("failed to generate key: %v", err)

     

       509
       509
       +
       	}

     

       510
       510
       +
       

     

       511
       511
       +
       	jwk := ecdsaPublicKeyToJWK(&privateKey.PublicKey)

     

       512
       512
       +
       	thumbprint, err := auth.CalculateJWKThumbprint(jwk)

     

       513
       513
       +
       	if err != nil {

     

       514
       514
       +
       		t.Fatalf("failed to calculate thumbprint: %v", err)

     

       515
       515
       +
       	}

     

       516
       516
       +
       

     

       517
       517
       +
       	claims := &auth.Claims{

     

       518
       518
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       519
       519
       +
       			Subject:   "did:plc:test123",

     

       520
       520
       +
       			Issuer:    "https://test.pds.local",

     

       521
       521
       +
       			ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),

     

       522
       522
       +
       			IssuedAt:  jwt.NewNumericDate(time.Now()),

     

       523
       523
       +
       		},

     

       524
       524
       +
       		Scope: "atproto",

     

       525
       525
       +
       		Confirmation: map[string]interface{}{

     

       526
       526
       +
       			"jkt": thumbprint,

     

       527
       527
       +
       		},

     

       528
       528
       +
       	}

     

       529
       529
       +
       

     

       530
       530
       +
       	middleware := NewAtProtoAuthMiddleware(&mockJWKSFetcher{}, false)

     

       531
       531
       +
       	defer middleware.Stop()

     

       532
       532
       +
       

     

       533
       533
       +
       	externalURI := "https://api.example.com/protected/resource"

     

       534
       534
       +
       	dpopProof := createDPoPProof(t, privateKey, "GET", externalURI)

     

       535
       535
       +
       

     

       536
       536
       +
       	req := httptest.NewRequest("GET", "http://internal-service/protected/resource", nil)

     

       537
       537
       +
       	req.Host = "api.example.com"

     

       538
       538
       +
       	req.Header.Set("X-Forwarded-Proto", "https")

     

       539
       539
       +
       

     

       540
       540
       +
       	proof, err := middleware.verifyDPoPBinding(req, claims, dpopProof)

     

       541
       541
       +
       	if err != nil {

     

       542
       542
       +
       		t.Fatalf("expected DPoP verification to succeed with forwarded proto, got %v", err)

     

       543
       543
       +
       	}

     

       544
       544
       +
       

     

       545
       545
       +
       	if proof == nil || proof.Claims == nil {

     

       546
       546
       +
       		t.Fatal("expected DPoP proof to be returned")

     

       547
       547
       +
       	}

     

       548
       548
       +
       }

     

       549
       549
       +
       

     

       550
       550
       +
       // TestMiddlewareStop tests that the middleware can be stopped properly

     

       551
       551
       +
       func TestMiddlewareStop(t *testing.T) {

     

       552
       552
       +
       	fetcher := &mockJWKSFetcher{}

     

       553
       553
       +
       	middleware := NewAtProtoAuthMiddleware(fetcher, false)

     

       554
       554
       +
       

     

       555
       555
       +
       	// Stop should not panic and should clean up resources

     

       556
       556
       +
       	middleware.Stop()

     

       557
       557
       +
       

     

       558
       558
       +
       	// Calling Stop again should also be safe (idempotent-ish)

     

       559
       559
       +
       	// Note: The underlying DPoPVerifier.Stop() closes a channel, so this might panic

     

       560
       560
       +
       	// if not handled properly. We test that at least one Stop works.

     

       561
       561
       +
       }

     

       562
       562
       +
       

     

       563
       563
       +
       // TestOptionalAuth_DPoPBoundToken_NoDPoPHeader tests that OptionalAuth treats

     

       564
       564
       +
       // tokens with cnf.jkt but no DPoP header as unauthenticated (potential token theft)

     

       565
       565
       +
       func TestOptionalAuth_DPoPBoundToken_NoDPoPHeader(t *testing.T) {

     

       566
       566
       +
       	// Generate a key pair for DPoP binding

     

       567
       567
       +
       	privateKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

     

       568
       568
       +
       	jwk := ecdsaPublicKeyToJWK(&privateKey.PublicKey)

     

       569
       569
       +
       	thumbprint, _ := auth.CalculateJWKThumbprint(jwk)

     

       570
       570
       +
       

     

       571
       571
       +
       	// Create a DPoP-bound token (has cnf.jkt)

     

       572
       572
       +
       	claims := auth.Claims{

     

       573
       573
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       574
       574
       +
       			Subject:   "did:plc:user123",

     

       575
       575
       +
       			Issuer:    "https://test.pds.local",

     

       576
       576
       +
       			ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),

     

       577
       577
       +
       			IssuedAt:  jwt.NewNumericDate(time.Now()),

     

       578
       578
       +
       		},

     

       579
       579
       +
       		Scope: "atproto",

     

       580
       580
       +
       		Confirmation: map[string]interface{}{

     

       581
       581
       +
       			"jkt": thumbprint,

     

       582
       582
       +
       		},

     

       583
       583
       +
       	}

     

       584
       584
       +
       

     

       585
       585
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodNone, claims)

     

       586
       586
       +
       	tokenString, _ := token.SignedString(jwt.UnsafeAllowNoneSignatureType)

     

       587
       587
       +
       

     

       588
       588
       +
       	// Use skipVerify=true to simulate a verified token

     

       589
       589
       +
       	// (In production, skipVerify would be false and VerifyJWT would be called)

     

       590
       590
       +
       	// However, for this test we need skipVerify=false to trigger DPoP checking

     

       591
       591
       +
       	// But the fetcher will fail, so let's use skipVerify=true and verify the logic

     

       592
       592
       +
       	// Actually, the DPoP check only happens when skipVerify=false

     

       593
       593
       +
       

     

       594
       594
       +
       	t.Run("with_skipVerify_false", func(t *testing.T) {

     

       595
       595
       +
       		// This will fail at JWT verification level, but that's expected

     

       596
       596
       +
       		// The important thing is the code path for DPoP checking

     

       597
       597
       +
       		fetcher := &mockJWKSFetcher{shouldFail: true}

     

       598
       598
       +
       		middleware := NewAtProtoAuthMiddleware(fetcher, false)

     

       599
       599
       +
       		defer middleware.Stop()

     

       600
       600
       +
       

     

       601
       601
       +
       		handlerCalled := false

     

       602
       602
       +
       		var capturedDID string

     

       603
       603
       +
       		handler := middleware.OptionalAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

     

       604
       604
       +
       			handlerCalled = true

     

       605
       605
       +
       			capturedDID = GetUserDID(r)

     

       606
       606
       +
       			w.WriteHeader(http.StatusOK)

     

       607
       607
       +
       		}))

     

       608
       608
       +
       

     

       609
       609
       +
       		req := httptest.NewRequest("GET", "/test", nil)

     

       610
       610
       +
       		req.Header.Set("Authorization", "Bearer "+tokenString)

     

       611
       611
       +
       		// Deliberately NOT setting DPoP header

     

       612
       612
       +
       		w := httptest.NewRecorder()

     

       613
       613
       +
       

     

       614
       614
       +
       		handler.ServeHTTP(w, req)

     

       615
       615
       +
       

     

       616
       616
       +
       		// Handler should be called (optional auth doesn't block)

     

       617
       617
       +
       		if !handlerCalled {

     

       618
       618
       +
       			t.Error("handler should be called")

     

       619
       619
       +
       		}

     

       620
       620
       +
       

     

       621
       621
       +
       		// But since JWT verification fails, user should not be authenticated

     

       622
       622
       +
       		if capturedDID != "" {

     

       623
       623
       +
       			t.Errorf("expected empty DID when verification fails, got %s", capturedDID)

     

       624
       624
       +
       		}

     

       625
       625
       +
       	})

     

       626
       626
       +
       

     

       627
       627
       +
       	t.Run("with_skipVerify_true_dpop_not_checked", func(t *testing.T) {

     

       628
       628
       +
       		// When skipVerify=true, DPoP is not checked (Phase 1 mode)

     

       629
       629
       +
       		fetcher := &mockJWKSFetcher{}

     

       630
       630
       +
       		middleware := NewAtProtoAuthMiddleware(fetcher, true)

     

       631
       631
       +
       		defer middleware.Stop()

     

       632
       632
       +
       

     

       633
       633
       +
       		handlerCalled := false

     

       634
       634
       +
       		var capturedDID string

     

       635
       635
       +
       		handler := middleware.OptionalAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

     

       636
       636
       +
       			handlerCalled = true

     

       637
       637
       +
       			capturedDID = GetUserDID(r)

     

       638
       638
       +
       			w.WriteHeader(http.StatusOK)

     

       639
       639
       +
       		}))

     

       640
       640
       +
       

     

       641
       641
       +
       		req := httptest.NewRequest("GET", "/test", nil)

     

       642
       642
       +
       		req.Header.Set("Authorization", "Bearer "+tokenString)

     

       643
       643
       +
       		// No DPoP header

     

       644
       644
       +
       		w := httptest.NewRecorder()

     

       645
       645
       +
       

     

       646
       646
       +
       		handler.ServeHTTP(w, req)

     

       647
       647
       +
       

     

       648
       648
       +
       		if !handlerCalled {

     

       649
       649
       +
       			t.Error("handler should be called")

     

       650
       650
       +
       		}

     

       651
       651
       +
       

     

       652
       652
       +
       		// With skipVerify=true, DPoP check is bypassed - token is trusted

     

       653
       653
       +
       		if capturedDID != "did:plc:user123" {

     

       654
       654
       +
       			t.Errorf("expected DID when skipVerify=true, got %s", capturedDID)

     

       655
       655
       +
       		}

     

       656
       656
       +
       	})

     

       657
       657
       +
       }

     

       658
       658
       +
       

     

       659
       659
       +
       // TestDPoPReplayProtection tests that the same DPoP proof cannot be used twice

     

       660
       660
       +
       func TestDPoPReplayProtection(t *testing.T) {

     

       661
       661
       +
       	// This tests the NonceCache functionality

     

       662
       662
       +
       	cache := auth.NewNonceCache(5 * time.Minute)

     

       663
       663
       +
       	defer cache.Stop()

     

       664
       664
       +
       

     

       665
       665
       +
       	jti := "unique-proof-id-123"

     

       666
       666
       +
       

     

       667
       667
       +
       	// First use should succeed

     

       668
       668
       +
       	if !cache.CheckAndStore(jti) {

     

       669
       669
       +
       		t.Error("First use of jti should succeed")

     

       670
       670
       +
       	}

     

       671
       671
       +
       

     

       672
       672
       +
       	// Second use should fail (replay detected)

     

       673
       673
       +
       	if cache.CheckAndStore(jti) {

     

       674
       674
       +
       		t.Error("SECURITY: Replay attack not detected - same jti accepted twice")

     

       675
       675
       +
       	}

     

       676
       676
       +
       

     

       677
       677
       +
       	// Different jti should succeed

     

       678
       678
       +
       	if !cache.CheckAndStore("different-jti-456") {

     

       679
       679
       +
       		t.Error("Different jti should succeed")

     

       680
       680
       +
       	}

     

       681
       681
       +
       }

     

       682
       682
       +
       

     

       683
       683
       +
       // Helper: createDPoPProof creates a DPoP proof JWT for testing

     

       684
       684
       +
       func createDPoPProof(t *testing.T, privateKey *ecdsa.PrivateKey, method, uri string) string {

     

       685
       685
       +
       	// Create JWK from public key

     

       686
       686
       +
       	jwk := ecdsaPublicKeyToJWK(&privateKey.PublicKey)

     

       687
       687
       +
       

     

       688
       688
       +
       	// Create DPoP claims with UUID for jti to ensure uniqueness across tests

     

       689
       689
       +
       	claims := auth.DPoPClaims{

     

       690
       690
       +
       		RegisteredClaims: jwt.RegisteredClaims{

     

       691
       691
       +
       			IssuedAt: jwt.NewNumericDate(time.Now()),

     

       692
       692
       +
       			ID:       uuid.New().String(),

     

       693
       693
       +
       		},

     

       694
       694
       +
       		HTTPMethod: method,

     

       695
       695
       +
       		HTTPURI:    uri,

     

       696
       696
       +
       	}

     

       697
       697
       +
       

     

       698
       698
       +
       	// Create token with custom header

     

       699
       699
       +
       	token := jwt.NewWithClaims(jwt.SigningMethodES256, claims)

     

       700
       700
       +
       	token.Header["typ"] = "dpop+jwt"

     

       701
       701
       +
       	token.Header["jwk"] = jwk

     

       702
       702
       +
       

     

       703
       703
       +
       	// Sign with private key

     

       704
       704
       +
       	signedToken, err := token.SignedString(privateKey)

     

       705
       705
       +
       	if err != nil {

     

       706
       706
       +
       		t.Fatalf("failed to sign DPoP proof: %v", err)

     

       707
       707
       +
       	}

     

       708
       708
       +
       

     

       709
       709
       +
       	return signedToken

     

       710
       710
       +
       }

     

       711
       711
       +
       

     

       712
       712
       +
       // Helper: ecdsaPublicKeyToJWK converts an ECDSA public key to JWK map

     

       713
       713
       +
       func ecdsaPublicKeyToJWK(pubKey *ecdsa.PublicKey) map[string]interface{} {

     

       714
       714
       +
       	// Get curve name

     

       715
       715
       +
       	var crv string

     

       716
       716
       +
       	switch pubKey.Curve {

     

       717
       717
       +
       	case elliptic.P256():

     

       718
       718
       +
       		crv = "P-256"

     

       719
       719
       +
       	case elliptic.P384():

     

       720
       720
       +
       		crv = "P-384"

     

       721
       721
       +
       	case elliptic.P521():

     

       722
       722
       +
       		crv = "P-521"

     

       723
       723
       +
       	default:

     

       724
       724
       +
       		panic("unsupported curve")

     

       725
       725
       +
       	}

     

       726
       726
       +
       

     

       727
       727
       +
       	// Encode coordinates

     

       728
       728
       +
       	xBytes := pubKey.X.Bytes()

     

       729
       729
       +
       	yBytes := pubKey.Y.Bytes()

     

       730
       730
       +
       

     

       731
       731
       +
       	// Ensure proper byte length (pad if needed)

     

       732
       732
       +
       	keySize := (pubKey.Curve.Params().BitSize + 7) / 8

     

       733
       733
       +
       	xPadded := make([]byte, keySize)

     

       734
       734
       +
       	yPadded := make([]byte, keySize)

     

       735
       735
       +
       	copy(xPadded[keySize-len(xBytes):], xBytes)

     

       736
       736
       +
       	copy(yPadded[keySize-len(yBytes):], yBytes)

     

       737
       737
       +
       

     

       738
       738
       +
       	return map[string]interface{}{

     

       739
       739
       +
       		"kty": "EC",

     

       740
       740
       +
       		"crv": crv,

     

       741
       741
       +
       		"x":   base64.RawURLEncoding.EncodeToString(xPadded),

     

       742
       742
       +
       		"y":   base64.RawURLEncoding.EncodeToString(yPadded),

     

       743
       743
       +
       	}

     

       744
       744
       +
       }

+134 -2

internal/atproto/auth/README.md

···

       110
       110
        
       5. Find matching key by `kid` from JWT header

     

       111
       111
        
       6. Cache the JWKS for 1 hour

     

       112
       112
        
       

     

       113
       113
       +
       ## DPoP Token Binding

     

       114
       114
       +
       

     

       115
       115
       +
       DPoP (Demonstrating Proof-of-Possession) binds access tokens to client-controlled cryptographic keys, preventing token theft and replay attacks.

     

       116
       116
       +
       

     

       117
       117
       +
       ### What is DPoP?

     

       118
       118
       +
       

     

       119
       119
       +
       DPoP is an OAuth extension (RFC 9449) that adds proof-of-possession semantics to bearer tokens. When a PDS issues a DPoP-bound access token:

     

       120
       120
       +
       

     

       121
       121
       +
       1. Access token contains `cnf.jkt` claim (JWK thumbprint of client's public key)

     

       122
       122
       +
       2. Client creates a DPoP proof JWT signed with their private key

     

       123
       123
       +
       3. Server verifies the proof signature and checks it matches the token's `cnf.jkt`

     

       124
       124
       +
       

     

       125
       125
       +
       ### CRITICAL: DPoP Security Model

     

       126
       126
       +
       

     

       127
       127
       +
       > ⚠️ **DPoP is an ADDITIONAL security layer, NOT a replacement for token signature verification.**

     

       128
       128
       +
       

     

       129
       129
       +
       The correct verification order is:

     

       130
       130
       +
       1. **ALWAYS verify the access token signature first** (via JWKS, HS256 shared secret, or DID resolution)

     

       131
       131
       +
       2. **If the verified token has `cnf.jkt`, REQUIRE valid DPoP proof**

     

       132
       132
       +
       3. **NEVER use DPoP as a fallback when signature verification fails**

     

       133
       133
       +
       

     

       134
       134
       +
       **Why This Matters**: An attacker could create a fake token with `sub: "did:plc:victim"` and their own `cnf.jkt`, then present a valid DPoP proof signed with their key. If we accept DPoP as a fallback, the attacker can impersonate any user.

     

       135
       135
       +
       

     

       136
       136
       +
       ### How DPoP Works

     

       137
       137
       +
       

     

       138
       138
       +
       ```

     

       139
       139
       +
       ┌─────────────┐                          ┌─────────────┐

     

       140
       140
       +
       │   Client    │                          │   Server    │

     

       141
       141
       +
       │             │                          │  (Coves)    │

     

       142
       142
       +
       └─────────────┘                          └─────────────┘

     

       143
       143
       +
              │                                        │

     

       144
       144
       +
              │ 1. Authorization: Bearer <token>       │

     

       145
       145
       +
              │    DPoP: <proof-jwt>                  │

     

       146
       146
       +
              │───────────────────────────────────────>│

     

       147
       147
       +
              │                                        │

     

       148
       148
       +
              │                                        │ 2. VERIFY token signature

     

       149
       149
       +
              │                                        │    (REQUIRED - no fallback!)

     

       150
       150
       +
              │                                        │

     

       151
       151
       +
              │                                        │ 3. If token has cnf.jkt:

     

       152
       152
       +
              │                                        │    - Verify DPoP proof

     

       153
       153
       +
              │                                        │    - Check thumbprint match

     

       154
       154
       +
              │                                        │

     

       155
       155
       +
              │                              200 OK    │

     

       156
       156
       +
              │<───────────────────────────────────────│

     

       157
       157
       +
       ```

     

       158
       158
       +
       

     

       159
       159
       +
       ### When DPoP is Required

     

       160
       160
       +
       

     

       161
       161
       +
       DPoP verification is **REQUIRED** when:

     

       162
       162
       +
       - Access token signature has been verified AND

     

       163
       163
       +
       - Access token contains `cnf.jkt` claim (DPoP-bound)

     

       164
       164
       +
       

     

       165
       165
       +
       If the token has `cnf.jkt` but no DPoP header is present, the request is **REJECTED**.

     

       166
       166
       +
       

     

       167
       167
       +
       ### Replay Protection

     

       168
       168
       +
       

     

       169
       169
       +
       DPoP proofs include a unique `jti` (JWT ID) claim. The server tracks seen `jti` values to prevent replay attacks:

     

       170
       170
       +
       

     

       171
       171
       +
       ```go

     

       172
       172
       +
       // Create a verifier with replay protection (default)

     

       173
       173
       +
       verifier := auth.NewDPoPVerifier()

     

       174
       174
       +
       defer verifier.Stop() // Stop cleanup goroutine on shutdown

     

       175
       175
       +
       

     

       176
       176
       +
       // The verifier automatically rejects reused jti values within the proof validity window (5 minutes)

     

       177
       177
       +
       ```

     

       178
       178
       +
       

     

       179
       179
       +
       ### DPoP Implementation

     

       180
       180
       +
       

     

       181
       181
       +
       The `dpop.go` module provides:

     

       182
       182
       +
       

     

       183
       183
       +
       ```go

     

       184
       184
       +
       // Create a verifier with replay protection

     

       185
       185
       +
       verifier := auth.NewDPoPVerifier()

     

       186
       186
       +
       defer verifier.Stop()

     

       187
       187
       +
       

     

       188
       188
       +
       // Verify the DPoP proof

     

       189
       189
       +
       proof, err := verifier.VerifyDPoPProof(dpopHeader, "POST", "https://coves.social/xrpc/...")

     

       190
       190
       +
       if err != nil {

     

       191
       191
       +
           // Invalid proof (includes replay detection)

     

       192
       192
       +
       }

     

       193
       193
       +
       

     

       194
       194
       +
       // Verify it binds to the VERIFIED access token

     

       195
       195
       +
       expectedThumbprint, err := auth.ExtractCnfJkt(claims)

     

       196
       196
       +
       if err != nil {

     

       197
       197
       +
           // Token not DPoP-bound

     

       198
       198
       +
       }

     

       199
       199
       +
       

     

       200
       200
       +
       if err := verifier.VerifyTokenBinding(proof, expectedThumbprint); err != nil {

     

       201
       201
       +
           // Proof doesn't match token

     

       202
       202
       +
       }

     

       203
       203
       +
       ```

     

       204
       204
       +
       

     

       205
       205
       +
       ### DPoP Proof Format

     

       206
       206
       +
       

     

       207
       207
       +
       The DPoP header contains a JWT with:

     

       208
       208
       +
       

     

       209
       209
       +
       **Header**:

     

       210
       210
       +
       - `typ`: `"dpop+jwt"` (required)

     

       211
       211
       +
       - `alg`: `"ES256"` (or other supported algorithm)

     

       212
       212
       +
       - `jwk`: Client's public key (JWK format)

     

       213
       213
       +
       

     

       214
       214
       +
       **Claims**:

     

       215
       215
       +
       - `jti`: Unique proof identifier (tracked for replay protection)

     

       216
       216
       +
       - `htm`: HTTP method (e.g., `"POST"`)

     

       217
       217
       +
       - `htu`: HTTP URI (without query/fragment)

     

       218
       218
       +
       - `iat`: Timestamp (must be recent, within 5 minutes)

     

       219
       219
       +
       

     

       220
       220
       +
       **Example**:

     

       221
       221
       +
       ```json

     

       222
       222
       +
       {

     

       223
       223
       +
         "typ": "dpop+jwt",

     

       224
       224
       +
         "alg": "ES256",

     

       225
       225
       +
         "jwk": {

     

       226
       226
       +
           "kty": "EC",

     

       227
       227
       +
           "crv": "P-256",

     

       228
       228
       +
           "x": "...",

     

       229
       229
       +
           "y": "..."

     

       230
       230
       +
         }

     

       231
       231
       +
       }

     

       232
       232
       +
       {

     

       233
       233
       +
         "jti": "unique-id-123",

     

       234
       234
       +
         "htm": "POST",

     

       235
       235
       +
         "htu": "https://coves.social/xrpc/social.coves.community.create",

     

       236
       236
       +
         "iat": 1700000000

     

       237
       237
       +
       }

     

       238
       238
       +
       ```

     

       239
       239
       +
       

     

       113
       240
        
       ## Security Considerations

     

       114
       241
        
       

     

       115
       242
        
       ### ✅ Implemented

     
···

       120
       247
        
       - Required claims validation (sub, iss)

     

       121
       248
        
       - Key caching with TTL

     

       122
       249
        
       - Secure error messages (no internal details leaked)

     

       250
       250
       +
       - **DPoP proof verification** (proof-of-possession for token binding)

     

       251
       251
       +
       - **DPoP thumbprint validation** (prevents token theft attacks)

     

       252
       252
       +
       - **DPoP freshness checks** (5-minute proof validity window)

     

       253
       253
       +
       - **DPoP replay protection** (jti tracking with in-memory cache)

     

       254
       254
       +
       - **Secure DPoP model** (DPoP required AFTER signature verification, never as fallback)

     

       123
       255
        
       

     

       124
       256
        
       ### ⚠️ Not Yet Implemented

     

       125
       257
        
       

     

       126
       126
       -
       - DPoP validation (for replay attack prevention)

     

       258
       258
       +
       - Server-issued DPoP nonces (additional replay protection)

     

       127
       259
        
       - Scope validation (checking `scope` claim)

     

       128
       260
        
       - Audience validation (checking `aud` claim)

     

       129
       261
        
       - Rate limiting per DID

     
···

       186
       318
        
       

     

       187
       319
        
       ## Future Enhancements

     

       188
       320
        
       

     

       189
       189
       -
       - [ ] DPoP proof validation

     

       321
       321
       +
       - [ ] DPoP nonce validation (server-managed nonce for additional replay protection)

     

       190
       322
        
       - [ ] Scope-based authorization

     

       191
       323
        
       - [ ] Audience claim validation

     

       192
       324
        
       - [ ] Token revocation support

+5 -6

go.mod

···

       1
       1
        
       module Coves

     

       2
       2
        
       

     

       3
       3
       -
       go 1.24.0

     

       3
       3
       +
       go 1.25

     

       4
       4
        
       

     

       5
       5
        
       require (

     

       6
       6
       -
       	github.com/bluesky-social/indigo v0.0.0-20251009212240-20524de167fe

     

       6
       6
       +
       	github.com/bluesky-social/indigo v0.0.0-20251127021457-6f2658724b36

     

       7
       7
        
       	github.com/go-chi/chi/v5 v5.2.1

     

       8
       8
        
       	github.com/golang-jwt/jwt/v5 v5.3.0

     

       9
       9
        
       	github.com/gorilla/websocket v1.5.3

     
···

       11
       11
        
       	github.com/lestrrat-go/jwx/v2 v2.0.12

     

       12
       12
        
       	github.com/lib/pq v1.10.9

     

       13
       13
        
       	github.com/pressly/goose/v3 v3.22.1

     

       14
       14
       -
       	github.com/stretchr/testify v1.9.0

     

       14
       14
       +
       	github.com/stretchr/testify v1.10.0

     

       15
       15
       +
       	github.com/xeipuuv/gojsonschema v1.2.0

     

       15
       16
        
       	golang.org/x/net v0.46.0

     

       16
       17
        
       	golang.org/x/time v0.3.0

     

       17
       18
        
       )

     

       18
       19
        
       

     

       19
       20
        
       require (

     

       20
       21
        
       	github.com/beorn7/perks v1.0.1 // indirect

     

       21
       21
       -
       	github.com/carlmjohnson/versioninfo v0.22.5 // indirect

     

       22
       22
        
       	github.com/cespare/xxhash/v2 v2.2.0 // indirect

     

       23
       23
        
       	github.com/davecgh/go-spew v1.1.1 // indirect

     

       24
       24
        
       	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.2.0 // indirect

     

       25
       25
       +
       	github.com/earthboundkid/versioninfo/v2 v2.24.1 // indirect

     

       25
       26
        
       	github.com/felixge/httpsnoop v1.0.4 // indirect

     

       26
       27
        
       	github.com/go-logr/logr v1.4.1 // indirect

     

       27
       28
        
       	github.com/go-logr/stdr v1.2.2 // indirect

     
···

       71
       72
        
       	github.com/segmentio/asm v1.2.0 // indirect

     

       72
       73
        
       	github.com/sethvargo/go-retry v0.3.0 // indirect

     

       73
       74
        
       	github.com/spaolacci/murmur3 v1.1.0 // indirect

     

       74
       74
       -
       	github.com/stretchr/objx v0.5.2 // indirect

     

       75
       75
        
       	github.com/whyrusleeping/cbor-gen v0.2.1-0.20241030202151-b7a6831be65e // indirect

     

       76
       76
        
       	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect

     

       77
       77
        
       	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect

     

       78
       78
       -
       	github.com/xeipuuv/gojsonschema v1.2.0 // indirect

     

       79
       78
        
       	gitlab.com/yawning/secp256k1-voi v0.0.0-20230925100816-f2616030848b // indirect

     

       80
       79
        
       	gitlab.com/yawning/tuplehash v0.0.0-20230713102510-df83abbf9a02 // indirect

     

       81
       80
        
       	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.46.1 // indirect

+6 -8

go.sum

···

       2
       2
        
       github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA=

     

       3
       3
        
       github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=

     

       4
       4
        
       github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=

     

       5
       5
       -
       github.com/bluesky-social/indigo v0.0.0-20251009212240-20524de167fe h1:VBhaqE5ewQgXbY5SfSWFZC/AwHFo7cHxZKFYi2ce9Yo=

     

       6
       6
       -
       github.com/bluesky-social/indigo v0.0.0-20251009212240-20524de167fe/go.mod h1:RuQVrCGm42QNsgumKaR6se+XkFKfCPNwdCiTvqKRUck=

     

       7
       7
       -
       github.com/carlmjohnson/versioninfo v0.22.5 h1:O00sjOLUAFxYQjlN/bzYTuZiS0y6fWDQjMRvwtKgwwc=

     

       8
       8
       -
       github.com/carlmjohnson/versioninfo v0.22.5/go.mod h1:QT9mph3wcVfISUKd0i9sZfVrPviHuSF+cUtLjm2WSf8=

     

       5
       5
       +
       github.com/bluesky-social/indigo v0.0.0-20251127021457-6f2658724b36 h1:Vc+l4sltxQfBT8qC3dm87PRYInmxlGyF1dmpjaW0WkU=

     

       6
       6
       +
       github.com/bluesky-social/indigo v0.0.0-20251127021457-6f2658724b36/go.mod h1:Pm2I1+iDXn/hLbF7XCg/DsZi6uDCiOo7hZGWprSM7k0=

     

       9
       7
        
       github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=

     

       10
       8
        
       github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=

     

       11
       9
        
       github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=

     
···

       17
       15
        
       github.com/decred/dcrd/dcrec/secp256k1/v4 v4.2.0/go.mod h1:v57UDF4pDQJcEfFUCRop3lJL149eHGSe9Jvczhzjo/0=

     

       18
       16
        
       github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=

     

       19
       17
        
       github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=

     

       18
       18
       +
       github.com/earthboundkid/versioninfo/v2 v2.24.1 h1:SJTMHaoUx3GzjjnUO1QzP3ZXK6Ee/nbWyCm58eY3oUg=

     

       19
       19
       +
       github.com/earthboundkid/versioninfo/v2 v2.24.1/go.mod h1:VcWEooDEuyUJnMfbdTh0uFN4cfEIg+kHMuWB2CDCLjw=

     

       20
       20
        
       github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=

     

       21
       21
        
       github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=

     

       22
       22
        
       github.com/go-chi/chi/v5 v5.2.1 h1:KOIHODQj58PmL80G2Eak4WdvUzjSJSm0vG72crDCqb8=

     
···

       172
       172
        
       github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=

     

       173
       173
        
       github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=

     

       174
       174
        
       github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=

     

       175
       175
       -
       github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=

     

       176
       176
       -
       github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=

     

       177
       175
        
       github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=

     

       178
       176
        
       github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=

     

       179
       177
        
       github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=

     
···

       182
       180
        
       github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=

     

       183
       181
        
       github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=

     

       184
       182
        
       github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=

     

       185
       185
       -
       github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=

     

       186
       186
       -
       github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=

     

       183
       183
       +
       github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=

     

       184
       184
       +
       github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=

     

       187
       185
        
       github.com/urfave/cli v1.22.10/go.mod h1:Gos4lmkARVdJ6EkW0WaNv/tZAAMe9V7XWyB60NtXRu0=

     

       188
       186
        
       github.com/warpfork/go-wish v0.0.0-20220906213052-39a1cc7a02d0 h1:GDDkbFiaK8jsSDJfjId/PEGEShv6ugrt4kYsC5UIDaQ=

     

       189
       187
        
       github.com/warpfork/go-wish v0.0.0-20220906213052-39a1cc7a02d0/go.mod h1:x6AKhvSSexNrVSrViXSHUEbICjmGXhtgABaHIySUSGw=

Compare changes