bretton.dev / coves
A community based topic aggregation platform built on atproto
fork atom

docs: document OAuth DPoP vote architecture change

Add comprehensive documentation explaining why vote write-forward
endpoints were removed:

- OAuth DPoP tokens are cryptographically bound to client's private key
- Backend cannot create DPoP proofs (doesn't have the key)
- Solution: Clients write directly to their PDS using
com.atproto.repo.createRecord/deleteRecord
- AppView indexes votes from Jetstream for aggregation

Also documented future work needed for subscriptions and blocking.

See: docs/PRD_BACKLOG.md#oauth-dpop-token-architecture

bretton.dev 9f788377 0a8e5c0a

options
unified split
Changed files
+79 -2
docs
PRD_BACKLOG.md
+79 -2
docs/PRD_BACKLOG.md 
···

       
13

       
 

       
## 🔴 P0: Critical (Alpha Blockers)


     

       
14

       
 

       



     

       
15

       
 

       
### OAuth DPoP Token Architecture - Voting Write-Forward


     

       
16

       
-

       
**Added:** 2025-11-02 | **Effort:** 4-6 hours | **Priority:** ALPHA BLOCKER


     

       
17

       
-

       
**Status:** ⚠️ ARCHITECTURE DECISION REQUIRED


     

       
18

       
 

       



     

       
19

       
 

       
**Problem:**


     

       
20

       
 

       
Our backend is attempting to use DPoP-bound OAuth tokens to write votes to users' PDSs, causing "Malformed token" errors. This violates atProto architecture patterns.


     
···

       
124

       
 

       
- Bluesky social-app: Direct PDS writes via agent


     

       
125

       
 

       
- atProto OAuth spec: DPoP binding prevents token reuse


     

       
126

       
 

       
- atProto architecture: AppView = read-only indexer


     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       
127

       
 

       



     

       
128

       
 

       
---


     

       
129

       
 

       



     
···

       
13

       
 

       
## 🔴 P0: Critical (Alpha Blockers)


     

       
14

       
 

       



     

       
15

       
 

       
### OAuth DPoP Token Architecture - Voting Write-Forward


     

       
16

       
+

       
**Added:** 2025-11-02 | **Completed:** 2025-11-02 | **Effort:** 2 hours | **Priority:** ALPHA BLOCKER


     

       
17

       
+

       
**Status:** ✅ COMPLETE


     

       
18

       
 

       



     

       
19

       
 

       
**Problem:**


     

       
20

       
 

       
Our backend is attempting to use DPoP-bound OAuth tokens to write votes to users' PDSs, causing "Malformed token" errors. This violates atProto architecture patterns.


     
···

       
124

       
 

       
- Bluesky social-app: Direct PDS writes via agent


     

       
125

       
 

       
- atProto OAuth spec: DPoP binding prevents token reuse


     

       
126

       
 

       
- atProto architecture: AppView = read-only indexer


     

       
127

       
+

       



     

       
128

       
+

       
---


     

       
129

       
+

       



     

       
130

       
+

       
### OAuth DPoP Token Architecture - Community Subscriptions


     

       
131

       
+

       
**Added:** 2025-11-02 | **Effort:** 1-2 hours | **Priority:** ALPHA BLOCKER


     

       
132

       
+

       
**Status:** 📋 TODO (Waiting for frontend implementation)


     

       
133

       
+

       



     

       
134

       
+

       
**Problem:**


     

       
135

       
+

       
Same DPoP token issue as voting - backend cannot use user's DPoP-bound OAuth tokens to write subscription records to user's PDS.


     

       
136

       
+

       



     

       
137

       
+

       
**Affected Operations:**


     

       
138

       
+

       
- `SubscribeToCommunity()` - [service.go:564-624](../internal/core/communities/service.go#L564-L624)


     

       
139

       
+

       
- `UnsubscribeFromCommunity()` - [service.go:626-660](../internal/core/communities/service.go#L626-L660)


     

       
140

       
+

       



     

       
141

       
+

       
**Collection:** `social.coves.community.subscription`


     

       
142

       
+

       



     

       
143

       
+

       
**Solution:**


     

       
144

       
+

       
Client writes directly using `com.atproto.repo.createRecord`:


     

       
145

       
+

       
```typescript


     

       
146

       
+

       
await agent.call('com.atproto.repo.createRecord', {


     

       
147

       
+

       
  repo: userDid,


     

       
148

       
+

       
  collection: 'social.coves.community.subscription',


     

       
149

       
+

       
  record: {


     

       
150

       
+

       
    $type: 'social.coves.community.subscription',


     

       
151

       
+

       
    subject: communityDid,


     

       
152

       
+

       
    contentVisibility: 3,


     

       
153

       
+

       
    createdAt: new Date().toISOString()


     

       
154

       
+

       
  }


     

       
155

       
+

       
})


     

       
156

       
+

       
```


     

       
157

       
+

       



     

       
158

       
+

       
**Backend Changes Needed:**


     

       
159

       
+

       
1. Remove write-forward from `SubscribeToCommunity()` and `UnsubscribeFromCommunity()`


     

       
160

       
+

       
2. Update handlers to return errors directing to client-direct pattern


     

       
161

       
+

       
3. Verify Jetstream consumer indexes subscriptions (already working)


     

       
162

       
+

       



     

       
163

       
+

       
**Files to Modify:**


     

       
164

       
+

       
- `internal/core/communities/service.go`


     

       
165

       
+

       
- `internal/api/handlers/community/subscribe.go`


     

       
166

       
+

       



     

       
167

       
+

       
---


     

       
168

       
+

       



     

       
169

       
+

       
### OAuth DPoP Token Architecture - Community Blocking


     

       
170

       
+

       
**Added:** 2025-11-02 | **Effort:** 1-2 hours | **Priority:** ALPHA BLOCKER


     

       
171

       
+

       
**Status:** 📋 TODO (Waiting for frontend implementation)


     

       
172

       
+

       



     

       
173

       
+

       
**Problem:**


     

       
174

       
+

       
Same DPoP token issue - backend cannot use user's DPoP-bound OAuth tokens to write block records to user's PDS.


     

       
175

       
+

       



     

       
176

       
+

       
**Affected Operations:**


     

       
177

       
+

       
- `BlockCommunity()` - [service.go:709-781](../internal/core/communities/service.go#L709-L781)


     

       
178

       
+

       
- `UnblockCommunity()` - [service.go:783-816](../internal/core/communities/service.go#L783-L816)


     

       
179

       
+

       



     

       
180

       
+

       
**Collection:** `social.coves.community.block`


     

       
181

       
+

       



     

       
182

       
+

       
**Solution:**


     

       
183

       
+

       
Client writes directly using `com.atproto.repo.createRecord`:


     

       
184

       
+

       
```typescript


     

       
185

       
+

       
await agent.call('com.atproto.repo.createRecord', {


     

       
186

       
+

       
  repo: userDid,


     

       
187

       
+

       
  collection: 'social.coves.community.block',


     

       
188

       
+

       
  record: {


     

       
189

       
+

       
    $type: 'social.coves.community.block',


     

       
190

       
+

       
    subject: communityDid,


     

       
191

       
+

       
    createdAt: new Date().toISOString()


     

       
192

       
+

       
  }


     

       
193

       
+

       
})


     

       
194

       
+

       
```


     

       
195

       
+

       



     

       
196

       
+

       
**Backend Changes Needed:**


     

       
197

       
+

       
1. Remove write-forward from `BlockCommunity()` and `UnblockCommunity()`


     

       
198

       
+

       
2. Update handlers to return errors directing to client-direct pattern


     

       
199

       
+

       
3. Verify Jetstream consumer indexes blocks (already working)


     

       
200

       
+

       



     

       
201

       
+

       
**Files to Modify:**


     

       
202

       
+

       
- `internal/core/communities/service.go`


     

       
203

       
+

       
- `internal/api/handlers/community/block.go`


     

       
204

       
 

       



     

       
205

       
 

       
---


     

       
206