···
1
+
# Phone Verification Branch Status
3
+
**Branch:** `feature/phone-verification`
4
+
**Status:** 🚧 Work in Progress - Pending SMS Provider Setup
5
+
**Created:** 2025-10-07
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
15
+
### 2. Database Schema (Complete)
16
+
- ✅ Migration 005: Phone verification tables
17
+
- ✅ Privacy-first: Only hashed phones stored
18
+
- ✅ Rate limiting tables
20
+
- ✅ Cleanup functions
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)
28
+
### 4. SMS Integration (Complete)
29
+
- ✅ Telnyx client implementation
30
+
- ✅ Decision documented (50% cheaper than Twilio)
31
+
- ✅ International number support
34
+
### 5. DID Configuration (Complete)
35
+
- ✅ `did:web:coves.social` DID document
36
+
- ✅ `.env.example` with all required variables
37
+
- ✅ Self-hostable (configurable DID)
39
+
### 6. Documentation (Complete)
41
+
- ✅ Complete implementation guide
42
+
- ✅ Security model documentation
43
+
- ✅ Quick reference summary
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
54
+
**Estimated time:** 1-2 hours (mostly waiting for account approval)
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)
66
+
**Estimated time:** 4-6 hours of coding
68
+
### 3. Frontend Integration
69
+
- [ ] Phone input screen (mobile app)
70
+
- [ ] OTP entry screen
71
+
- [ ] Verification badge display
72
+
- [ ] Re-verification flow
74
+
**Estimated time:** 8-12 hours (mobile + web)
77
+
- [ ] Unit tests (service layer)
78
+
- [ ] Integration tests (XRPC endpoints)
79
+
- [ ] E2E test (full verification flow)
80
+
- [ ] Security tests (rate limiting, signature verification)
82
+
**Estimated time:** 6-8 hours
84
+
## Can We Merge Lexicon Changes Now?
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
96
+
**Option 1: Merge lexicon only**
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"
105
+
**Option 2: Keep everything in branch**
106
+
- Wait until SMS provider is set up
107
+
- Implement remaining components
109
+
- Merge entire feature at once
111
+
**Recommendation:** Option 2 (keep in branch for now)
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.
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
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)
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)
141
+
### Development Cost
142
+
- **SMS Provider**: Telnyx - $0/month base + usage
143
+
- **Development Time**: ~20-30 hours total (backend + frontend + testing)
145
+
### Operational Cost (Production)
146
+
- **SMS**: $0.004/verification
147
+
- **Expected**: 10,000 verifications/month = **$40/month**
148
+
- **Annual re-verification**: Ongoing cost
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
161
+
## Questions Resolved
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.
166
+
### Q: What if someone copies a verification signature?
167
+
**A:** Signature includes subject DID, so copying fails verification. See VERIFICATION_SECURITY.md.
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.
174
+
For questions about this branch:
175
+
- Check docs/PHONE_VERIFICATION_*.md
181
+
**Last Updated:** 2025-10-07
182
+
**Branch Status:** Ready for SMS provider setup + implementation
bretton.dev