bretton.dev / coves
A community based topic aggregation platform built on atproto
fork atom
coves / docs / PHONE_VERIFICATION_BRANCH_STATUS.md
at feature/phone-verification 5.6 kB view raw view code

Phone Verification Branch Status#

Branch: feature/phone-verification Status: 🚧 Work in Progress - Pending SMS Provider Setup Created: 2025-10-07

What's Done ✅#

1. Lexicon Design (Complete)#

  • ✅ Updated social.coves.actor.profile with verifications array
  • ✅ Created XRPC endpoints: requestPhone, verifyPhone, getStatus
  • ✅ Backwards-compatible (optional field)
  • ✅ Safe to merge to main - lexicon changes are additive only

2. Database Schema (Complete)#

  • ✅ Migration 005: Phone verification tables
  • ✅ Privacy-first: Only hashed phones stored
  • ✅ Rate limiting tables
  • ✅ Audit logging
  • ✅ Cleanup functions

3. Service Layer (Complete)#

  • ✅ Verification service with full business logic
  • ✅ Security features (OTP, rate limiting, signatures)
  • ✅ Domain errors for XRPC error mapping
  • ✅ Interface-based design (testable)

4. SMS Integration (Complete)#

  • ✅ Telnyx client implementation
  • ✅ Decision documented (50% cheaper than Twilio)
  • ✅ International number support
  • ✅ Error handling

5. DID Configuration (Complete)#

  • ✅ did:web:coves.social DID document
  • ✅ .env.example with all required variables
  • ✅ Self-hostable (configurable DID)

6. Documentation (Complete)#

  • ✅ DID setup guide
  • ✅ Complete implementation guide
  • ✅ Security model documentation
  • ✅ Quick reference summary

What's Pending 🚧#

1. SMS Provider Setup#

Why we're blocked:

  • Need to sign up for Telnyx/Plivo
  • Get API credentials
  • Purchase phone number
  • Test SMS delivery

Estimated time: 1-2 hours (mostly waiting for account approval)

2. Missing Go Implementations#

Still need to write:

  • PhoneHashProvider (HMAC-SHA256 implementation)
  • SignatureService (ECDSA P-256 signing with private key)
  • PDSWriter (write verifications to user's PDS via OAuth)
  • VerificationRepository (PostgreSQL implementation)
  • XRPC handlers (routes + error mapping)
  • Integration with main.go (wire up services)
  • Background cleanup job (expired OTP requests)

Estimated time: 4-6 hours of coding

3. Frontend Integration#

  • Phone input screen (mobile app)
  • OTP entry screen
  • Verification badge display
  • Re-verification flow

Estimated time: 8-12 hours (mobile + web)

4. Testing#

  • Unit tests (service layer)
  • Integration tests (XRPC endpoints)
  • E2E test (full verification flow)
  • Security tests (rate limiting, signature verification)

Estimated time: 6-8 hours

Can We Merge Lexicon Changes Now?#

YES! ✅

The lexicon changes are safe to merge because:

  1. Backwards compatible - verifications is optional
  2. Additive only - No fields removed or changed
  3. Future-proof - Works for email/domain verification too
  4. No breaking changes - Old clients ignore unknown fields

Merge Strategy#

Option 1: Merge lexicon only

git checkout main
git checkout feature/phone-verification -- internal/atproto/lexicon/social/coves/actor/profile.json
git checkout feature/phone-verification -- internal/atproto/lexicon/social/coves/verification/
git commit -m "feat: Add verification array to actor lexicon"
git push

Option 2: Keep everything in branch

  • Wait until SMS provider is set up
  • Implement remaining components
  • Test end-to-end
  • Merge entire feature at once

Recommendation: Option 2 (keep in branch for now)

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.

Next Steps#

Immediate (When ready to continue)#

  1. Sign up for Telnyx: https://telnyx.com
  2. Get API key + messaging profile
  3. Purchase phone number
  4. Update .env with credentials

Then Implement#

  1. PhoneHashProvider (30 mins)
  2. SignatureService (1 hour)
  3. PDSWriter (1 hour)
  4. VerificationRepository (2 hours)
  5. XRPC handlers (1 hour)
  6. Wire up in main.go (30 mins)
  7. Background cleanup job (30 mins)

Testing#

  1. Run migration on test DB
  2. Test OTP request flow
  3. Test verification flow
  4. Test rate limiting
  5. Test signature verification (third-party app perspective)

Cost Estimate#

Development Cost#

  • SMS Provider: Telnyx - $0/month base + usage
  • Development Time: ~20-30 hours total (backend + frontend + testing)

Operational Cost (Production)#

  • SMS: $0.004/verification
  • Expected: 10,000 verifications/month = $40/month
  • Annual re-verification: Ongoing cost

Branch History#

4b17f66 docs: Add comprehensive phone verification documentation
5f123c8 feat: Add did:web configuration for verification signing
ebf0974 feat: Add Telnyx SMS integration
ea00d84 feat: Add phone verification service layer
0705a59 feat: Add database schema for phone verification
583c3d4 feat: Add verification system to actor lexicon

Questions Resolved#

Q: Can we add fields to lexicons after they're published?#

A: Yes! Adding optional fields is safe. Removing or changing fields is dangerous.

Q: What if someone copies a verification signature?#

A: Signature includes subject DID, so copying fails verification. See VERIFICATION_SECURITY.md.

Q: Why .well-known/did.json instead of DNS?#

A: It's the standard did:web method. DNS TXT is optional extra layer.

Contact#

For questions about this branch:

  • Check docs/PHONE_VERIFICATION_*.md
  • Open an issue
  • Ask in Discord

Last Updated: 2025-10-07 Branch Status: Ready for SMS provider setup + implementation