A community based topic aggregation platform built on atproto
bretton.dev
docs: Add branch status and remaining work tracker
Document what's complete and what's pending for phone verification.
Includes merge strategy, cost estimates, and next steps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
+182
docs/PHONE_VERIFICATION_BRANCH_STATUS.md
+182
docs/PHONE_VERIFICATION_BRANCH_STATUS.md
···
···
1
+
# Phone Verification Branch Status
2
+
3
+
**Branch:** `feature/phone-verification`
4
+
**Status:** 🚧 Work in Progress - Pending SMS Provider Setup
5
+
**Created:** 2025-10-07
6
+
7
+
## What's Done ✅
8
+
9
+
### 1. Lexicon Design (Complete)
10
+
- ✅ Updated `social.coves.actor.profile` with `verifications` array
11
+
- ✅ Created XRPC endpoints: `requestPhone`, `verifyPhone`, `getStatus`
12
+
- ✅ Backwards-compatible (optional field)
13
+
- ✅ **Safe to merge to main** - lexicon changes are additive only
14
+
15
+
### 2. Database Schema (Complete)
16
+
- ✅ Migration 005: Phone verification tables
17
+
- ✅ Privacy-first: Only hashed phones stored
18
+
- ✅ Rate limiting tables
19
+
- ✅ Audit logging
20
+
- ✅ Cleanup functions
21
+
22
+
### 3. Service Layer (Complete)
23
+
- ✅ Verification service with full business logic
24
+
- ✅ Security features (OTP, rate limiting, signatures)
25
+
- ✅ Domain errors for XRPC error mapping
26
+
- ✅ Interface-based design (testable)
27
+
28
+
### 4. SMS Integration (Complete)
29
+
- ✅ Telnyx client implementation
30
+
- ✅ Decision documented (50% cheaper than Twilio)
31
+
- ✅ International number support
32
+
- ✅ Error handling
33
+
34
+
### 5. DID Configuration (Complete)
35
+
- ✅ `did:web:coves.social` DID document
36
+
- ✅ `.env.example` with all required variables
37
+
- ✅ Self-hostable (configurable DID)
38
+
39
+
### 6. Documentation (Complete)
40
+
- ✅ DID setup guide
41
+
- ✅ Complete implementation guide
42
+
- ✅ Security model documentation
43
+
- ✅ Quick reference summary
44
+
45
+
## What's Pending 🚧
46
+
47
+
### 1. SMS Provider Setup
48
+
**Why we're blocked:**
49
+
- Need to sign up for Telnyx/Plivo
50
+
- Get API credentials
51
+
- Purchase phone number
52
+
- Test SMS delivery
53
+
54
+
**Estimated time:** 1-2 hours (mostly waiting for account approval)
55
+
56
+
### 2. Missing Go Implementations
57
+
Still need to write:
58
+
- [ ] `PhoneHashProvider` (HMAC-SHA256 implementation)
59
+
- [ ] `SignatureService` (ECDSA P-256 signing with private key)
60
+
- [ ] `PDSWriter` (write verifications to user's PDS via OAuth)
61
+
- [ ] `VerificationRepository` (PostgreSQL implementation)
62
+
- [ ] XRPC handlers (routes + error mapping)
63
+
- [ ] Integration with main.go (wire up services)
64
+
- [ ] Background cleanup job (expired OTP requests)
65
+
66
+
**Estimated time:** 4-6 hours of coding
67
+
68
+
### 3. Frontend Integration
69
+
- [ ] Phone input screen (mobile app)
70
+
- [ ] OTP entry screen
71
+
- [ ] Verification badge display
72
+
- [ ] Re-verification flow
73
+
74
+
**Estimated time:** 8-12 hours (mobile + web)
75
+
76
+
### 4. Testing
77
+
- [ ] Unit tests (service layer)
78
+
- [ ] Integration tests (XRPC endpoints)
79
+
- [ ] E2E test (full verification flow)
80
+
- [ ] Security tests (rate limiting, signature verification)
81
+
82
+
**Estimated time:** 6-8 hours
83
+
84
+
## Can We Merge Lexicon Changes Now?
85
+
86
+
**YES!** ✅
87
+
88
+
The lexicon changes are safe to merge because:
89
+
1. **Backwards compatible** - `verifications` is optional
90
+
2. **Additive only** - No fields removed or changed
91
+
3. **Future-proof** - Works for email/domain verification too
92
+
4. **No breaking changes** - Old clients ignore unknown fields
93
+
94
+
### Merge Strategy
95
+
96
+
**Option 1: Merge lexicon only**
97
+
```bash
98
+
git checkout main
99
+
git checkout feature/phone-verification -- internal/atproto/lexicon/social/coves/actor/profile.json
100
+
git checkout feature/phone-verification -- internal/atproto/lexicon/social/coves/verification/
101
+
git commit -m "feat: Add verification array to actor lexicon"
102
+
git push
103
+
```
104
+
105
+
**Option 2: Keep everything in branch**
106
+
- Wait until SMS provider is set up
107
+
- Implement remaining components
108
+
- Test end-to-end
109
+
- Merge entire feature at once
110
+
111
+
**Recommendation:** Option 2 (keep in branch for now)
112
+
113
+
Even though the lexicon is safe, it's cleaner to merge the entire feature together once it's working. This prevents confusion about why there's a `verifications` field that nothing uses yet.
114
+
115
+
## Next Steps
116
+
117
+
### Immediate (When ready to continue)
118
+
1. Sign up for Telnyx: https://telnyx.com
119
+
2. Get API key + messaging profile
120
+
3. Purchase phone number
121
+
4. Update `.env` with credentials
122
+
123
+
### Then Implement
124
+
1. `PhoneHashProvider` (30 mins)
125
+
2. `SignatureService` (1 hour)
126
+
3. `PDSWriter` (1 hour)
127
+
4. `VerificationRepository` (2 hours)
128
+
5. XRPC handlers (1 hour)
129
+
6. Wire up in main.go (30 mins)
130
+
7. Background cleanup job (30 mins)
131
+
132
+
### Testing
133
+
1. Run migration on test DB
134
+
2. Test OTP request flow
135
+
3. Test verification flow
136
+
4. Test rate limiting
137
+
5. Test signature verification (third-party app perspective)
138
+
139
+
## Cost Estimate
140
+
141
+
### Development Cost
142
+
- **SMS Provider**: Telnyx - $0/month base + usage
143
+
- **Development Time**: ~20-30 hours total (backend + frontend + testing)
144
+
145
+
### Operational Cost (Production)
146
+
- **SMS**: $0.004/verification
147
+
- **Expected**: 10,000 verifications/month = **$40/month**
148
+
- **Annual re-verification**: Ongoing cost
149
+
150
+
## Branch History
151
+
152
+
```
153
+
4b17f66 docs: Add comprehensive phone verification documentation
154
+
5f123c8 feat: Add did:web configuration for verification signing
155
+
ebf0974 feat: Add Telnyx SMS integration
156
+
ea00d84 feat: Add phone verification service layer
157
+
0705a59 feat: Add database schema for phone verification
158
+
583c3d4 feat: Add verification system to actor lexicon
159
+
```
160
+
161
+
## Questions Resolved
162
+
163
+
### Q: Can we add fields to lexicons after they're published?
164
+
**A:** Yes! Adding optional fields is safe. Removing or changing fields is dangerous.
165
+
166
+
### Q: What if someone copies a verification signature?
167
+
**A:** Signature includes subject DID, so copying fails verification. See VERIFICATION_SECURITY.md.
168
+
169
+
### Q: Why .well-known/did.json instead of DNS?
170
+
**A:** It's the standard did:web method. DNS TXT is optional extra layer.
171
+
172
+
## Contact
173
+
174
+
For questions about this branch:
175
+
- Check docs/PHONE_VERIFICATION_*.md
176
+
- Open an issue
177
+
- Ask in Discord
178
+
179
+
---
180
+
181
+
**Last Updated:** 2025-10-07
182
+
**Branch Status:** Ready for SMS provider setup + implementation