commit 4b17f66201eb79bee1f540dcaaefcfdaa4a78250 · bretton.dev/coves

+96

docs/DID_SETUP.md

···

       1
       1
       +
       # DID Setup for Coves Verification Service

     

       2
       2
       +
       

     

       3
       3
       +
       ## Overview

     

       4
       4
       +
       Coves uses a `did:web` DID to sign phone verification tokens. This allows third-party clients to cryptographically verify that verifications were issued by the official Coves service.

     

       5
       5
       +
       

     

       6
       6
       +
       ## Generating the Verification Keypair

     

       7
       7
       +
       

     

       8
       8
       +
       ```bash

     

       9
       9
       +
       # Generate P-256 EC keypair for signing verifications

     

       10
       10
       +
       openssl ecparam -name prime256v1 -genkey -noout -out verification-key.pem

     

       11
       11
       +
       

     

       12
       12
       +
       # Extract public key in JWK format

     

       13
       13
       +
       # You'll need to convert this to JWK format for the DID document

     

       14
       14
       +
       openssl ec -in verification-key.pem -pubout -out verification-key-pub.pem

     

       15
       15
       +
       ```

     

       16
       16
       +
       

     

       17
       17
       +
       ## Converting to JWK Format

     

       18
       18
       +
       

     

       19
       19
       +
       Use a tool or library to convert the public key to JWK format:

     

       20
       20
       +
       - Go: `github.com/lestrrat-go/jwx/v2/jwk`

     

       21
       21
       +
       - Node.js: `jose` library

     

       22
       22
       +
       - Online: https://8gwifi.org/jwkconvertfunctions.jsp (for dev only)

     

       23
       23
       +
       

     

       24
       24
       +
       ## Updating the DID Document

     

       25
       25
       +
       

     

       26
       26
       +
       1. Generate the keypair

     

       27
       27
       +
       2. Extract the public key JWK (x, y coordinates)

     

       28
       28
       +
       3. Update `.well-known/did.json` with the actual coordinates

     

       29
       29
       +
       4. Store the private key securely (environment variable or secrets manager)

     

       30
       30
       +
       

     

       31
       31
       +
       ## Serving the DID Document

     

       32
       32
       +
       

     

       33
       33
       +
       The DID document must be served at:

     

       34
       34
       +
       ```

     

       35
       35
       +
       https://coves.social/.well-known/did.json

     

       36
       36
       +
       ```

     

       37
       37
       +
       

     

       38
       38
       +
       With headers:

     

       39
       39
       +
       ```

     

       40
       40
       +
       Content-Type: application/json

     

       41
       41
       +
       Access-Control-Allow-Origin: *

     

       42
       42
       +
       ```

     

       43
       43
       +
       

     

       44
       44
       +
       ## Environment Configuration

     

       45
       45
       +
       

     

       46
       46
       +
       **DO NOT commit secrets to git!**

     

       47
       47
       +
       

     

       48
       48
       +
       Add to your `.env` file:

     

       49
       49
       +
       ```bash

     

       50
       50
       +
       # DID for your instance (change coves.social to your domain)

     

       51
       51
       +
       VERIFICATION_SERVICE_DID=did:web:coves.social

     

       52
       52
       +
       

     

       53
       53
       +
       # Private key (base64-encoded or plain PEM)

     

       54
       54
       +
       VERIFICATION_PRIVATE_KEY="$(cat verification-key.pem | base64 -w 0)"

     

       55
       55
       +
       ```

     

       56
       56
       +
       

     

       57
       57
       +
       In production, use a secrets manager:

     

       58
       58
       +
       - AWS Secrets Manager

     

       59
       59
       +
       - HashiCorp Vault

     

       60
       60
       +
       - Google Secret Manager

     

       61
       61
       +
       

     

       62
       62
       +
       **For forked deployments:**

     

       63
       63
       +
       If you're deploying your own instance at `myapp.com`, update:

     

       64
       64
       +
       1. `VERIFICATION_SERVICE_DID=did:web:myapp.com`

     

       65
       65
       +
       2. Serve DID document at `https://myapp.com/.well-known/did.json`

     

       66
       66
       +
       3. Update `verificationMethod[0].id` to use your domain

     

       67
       67
       +
       

     

       68
       68
       +
       ## Verifying Signatures (Third-Party Clients)

     

       69
       69
       +
       

     

       70
       70
       +
       Third-party clients can verify phone verifications by:

     

       71
       71
       +
       

     

       72
       72
       +
       1. Fetch DID document: `https://coves.social/.well-known/did.json`

     

       73
       73
       +
       2. Extract public key from `verificationMethod[0].publicKeyJwk`

     

       74
       74
       +
       3. Verify signature over verification data:

     

       75
       75
       +
          ```

     

       76
       76
       +
          payload = type + verifiedBy + verifiedAt + expiresAt + subjectDID

     

       77
       77
       +
          verify(payload, signature, publicKey)

     

       78
       78
       +
          ```

     

       79
       79
       +
       

     

       80
       80
       +
       ## Key Rotation

     

       81
       81
       +
       

     

       82
       82
       +
       When rotating keys:

     

       83
       83
       +
       1. Generate new keypair

     

       84
       84
       +
       2. Add new key to `verificationMethod` array with new ID (#verification-key-2)

     

       85
       85
       +
       3. Keep old key for 30 days to allow verification of existing tokens

     

       86
       86
       +
       4. Update signing code to use new key

     

       87
       87
       +
       5. After 30 days, remove old key from DID document

     

       88
       88
       +
       

     

       89
       89
       +
       ## Testing

     

       90
       90
       +
       

     

       91
       91
       +
       ```bash

     

       92
       92
       +
       # Verify DID document is valid

     

       93
       93
       +
       curl https://coves.social/.well-known/did.json | jq .

     

       94
       94
       +
       

     

       95
       95
       +
       # Should return valid JSON with your public key

     

       96
       96
       +
       ```

+297

docs/PHONE_VERIFICATION_IMPLEMENTATION.md

···

       1
       1
       +
       # Phone Verification Implementation Guide

     

       2
       2
       +
       

     

       3
       3
       +
       ## Overview

     

       4
       4
       +
       This document outlines the complete implementation of phone verification for Coves using the hybrid approach: privacy-first storage with cryptographically signed, portable verification badges.

     

       5
       5
       +
       

     

       6
       6
       +
       ## Architecture

     

       7
       7
       +
       

     

       8
       8
       +
       ### Data Flow

     

       9
       9
       +
       ```

     

       10
       10
       +
       1. User requests verification (mobile app)

     

       11
       11
       +
          ↓

     

       12
       12
       +
       2. Coves AppView validates + sends OTP via Telnyx

     

       13
       13
       +
          ↓

     

       14
       14
       +
       3. User enters OTP code

     

       15
       15
       +
          ↓

     

       16
       16
       +
       4. AppView validates code + creates signed verification

     

       17
       17
       +
          ↓

     

       18
       18
       +
       5. AppView writes verification to user's PDS profile

     

       19
       19
       +
          ↓

     

       20
       20
       +
       6. AppView stores phone_hash in local database

     

       21
       21
       +
          ↓

     

       22
       22
       +
       7. Third-party clients see verification badge (portable)

     

       23
       23
       +
       ```

     

       24
       24
       +
       

     

       25
       25
       +
       ### Privacy Model

     

       26
       26
       +
       - **Never stored**: Plain phone numbers (anywhere)

     

       27
       27
       +
       - **Hashed in AppView DB**: HMAC-SHA256(phone, pepper) for duplicate detection

     

       28
       28
       +
       - **Stored on PDS**: Signed verification badge (no phone data)

     

       29
       29
       +
       - **Portable**: Badge works across AppViews, can't be forged

     

       30
       30
       +
       

     

       31
       31
       +
       ## Components Implemented

     

       32
       32
       +
       

     

       33
       33
       +
       ### 1. Lexicon Updates

     

       34
       34
       +
       - ✅ **actor/profile.json**: Added `verifications` array

     

       35
       35
       +
       - ✅ **verification/requestPhone.json**: XRPC endpoint for OTP request

     

       36
       36
       +
       - ✅ **verification/verifyPhone.json**: XRPC endpoint for OTP validation

     

       37
       37
       +
       - ✅ **verification/getStatus.json**: XRPC endpoint for verification status

     

       38
       38
       +
       

     

       39
       39
       +
       ### 2. Database Schema (005_create_phone_verification_tables.sql)

     

       40
       40
       +
       ```sql

     

       41
       41
       +
       phone_verifications              -- Completed verifications

     

       42
       42
       +
       phone_verification_requests      -- Pending OTP requests (10min TTL)

     

       43
       43
       +
       phone_verification_rate_limits   -- Rate limit tracking

     

       44
       44
       +
       phone_verification_audit_log     -- Security audit trail

     

       45
       45
       +
       ```

     

       46
       46
       +
       

     

       47
       47
       +
       ### 3. did:web DID for Coves

     

       48
       48
       +
       - **Location**: `.well-known/did.json`

     

       49
       49
       +
       - **DID**: `did:web:coves.social`

     

       50
       50
       +
       - **Purpose**: Signs verification badges

     

       51
       51
       +
       - **Public Key**: P-256 EC key (JWK format)

     

       52
       52
       +
       

     

       53
       53
       +
       ### 4. Core Service Layer

     

       54
       54
       +
       - **interfaces.go**: Service contracts

     

       55
       55
       +
       - **service.go**: Verification logic

     

       56
       56
       +
       - **errors.go**: Domain errors

     

       57
       57
       +
       

     

       58
       58
       +
       ### 5. SMS Provider (Telnyx)

     

       59
       59
       +
       - **telnyx/client.go**: API integration

     

       60
       60
       +
       - **Why Telnyx**: 50% cheaper, owned infrastructure, international support

     

       61
       61
       +
       

     

       62
       62
       +
       ## Environment Configuration

     

       63
       63
       +
       

     

       64
       64
       +
       ### Required Variables (.env)

     

       65
       65
       +
       ```bash

     

       66
       66
       +
       # DID Configuration

     

       67
       67
       +
       VERIFICATION_SERVICE_DID=did:web:coves.social

     

       68
       68
       +
       VERIFICATION_PRIVATE_KEY=<base64-encoded-P256-private-key>

     

       69
       69
       +
       

     

       70
       70
       +
       # Telnyx Configuration

     

       71
       71
       +
       TELNYX_API_KEY=<your-api-key>

     

       72
       72
       +
       TELNYX_MESSAGING_PROFILE_ID=<your-profile-id>

     

       73
       73
       +
       TELNYX_FROM_NUMBER=<e164-phone-number>

     

       74
       74
       +
       

     

       75
       75
       +
       # Security

     

       76
       76
       +
       PHONE_HASH_PEPPER=<base64-32-bytes>  # NEVER change after initial setup!

     

       77
       77
       +
       ```

     

       78
       78
       +
       

     

       79
       79
       +
       ### Setup Steps

     

       80
       80
       +
       

     

       81
       81
       +
       #### 1. Generate DID Keypair

     

       82
       82
       +
       ```bash

     

       83
       83
       +
       # Generate P-256 EC private key

     

       84
       84
       +
       openssl ecparam -name prime256v1 -genkey -noout -out verification-key.pem

     

       85
       85
       +
       

     

       86
       86
       +
       # Extract public key

     

       87
       87
       +
       openssl ec -in verification-key.pem -pubout -out verification-key-pub.pem

     

       88
       88
       +
       

     

       89
       89
       +
       # Convert to JWK format (use library or online tool for dev)

     

       90
       90
       +
       # Update .well-known/did.json with x, y coordinates

     

       91
       91
       +
       

     

       92
       92
       +
       # Store private key in environment

     

       93
       93
       +
       export VERIFICATION_PRIVATE_KEY="$(cat verification-key.pem | base64 -w 0)"

     

       94
       94
       +
       ```

     

       95
       95
       +
       

     

       96
       96
       +
       #### 2. Generate Phone Hash Pepper

     

       97
       97
       +
       ```bash

     

       98
       98
       +
       export PHONE_HASH_PEPPER="$(openssl rand -base64 32)"

     

       99
       99
       +
       ```

     

       100
       100
       +
       

     

       101
       101
       +
       ⚠️ **CRITICAL**: Never change `PHONE_HASH_PEPPER` after production launch!

     

       102
       102
       +
       

     

       103
       103
       +
       #### 3. Configure Telnyx

     

       104
       104
       +
       1. Sign up at https://telnyx.com

     

       105
       105
       +
       2. Create a Messaging Profile

     

       106
       106
       +
       3. Purchase a phone number

     

       107
       107
       +
       4. Get API key from dashboard

     

       108
       108
       +
       5. Add to `.env`

     

       109
       109
       +
       

     

       110
       110
       +
       #### 4. Serve DID Document

     

       111
       111
       +
       Ensure `https://coves.social/.well-known/did.json` is publicly accessible with:

     

       112
       112
       +
       ```

     

       113
       113
       +
       Content-Type: application/json

     

       114
       114
       +
       Access-Control-Allow-Origin: *

     

       115
       115
       +
       ```

     

       116
       116
       +
       

     

       117
       117
       +
       ## Implementation Checklist

     

       118
       118
       +
       

     

       119
       119
       +
       ### Backend (Go)

     

       120
       120
       +
       - [ ] Run migration: `005_create_phone_verification_tables.sql`

     

       121
       121
       +
       - [ ] Implement `PhoneHashProvider` (HMAC-SHA256 with pepper)

     

       122
       122
       +
       - [ ] Implement `SignatureService` (ECDSA P-256 signing)

     

       123
       123
       +
       - [ ] Implement `PDSWriter` (write to user's PDS via OAuth)

     

       124
       124
       +
       - [ ] Implement `VerificationRepository` (PostgreSQL)

     

       125
       125
       +
       - [ ] Create XRPC handlers for verification endpoints

     

       126
       126
       +
       - [ ] Add verification routes to main.go

     

       127
       127
       +
       - [ ] Add background cleanup job (expired requests)

     

       128
       128
       +
       

     

       129
       129
       +
       ### Frontend (Mobile)

     

       130
       130
       +
       - [ ] Add phone input screen with E.164 validation

     

       131
       131
       +
       - [ ] Add OTP entry screen (6-digit code)

     

       132
       132
       +
       - [ ] Call `/xrpc/social.coves.verification.requestPhone`

     

       133
       133
       +
       - [ ] Call `/xrpc/social.coves.verification.verifyPhone`

     

       134
       134
       +
       - [ ] Display verification badge on profiles

     

       135
       135
       +
       - [ ] Handle re-verification flow (annual)

     

       136
       136
       +
       

     

       137
       137
       +
       ### Testing

     

       138
       138
       +
       - [ ] Unit tests for service layer

     

       139
       139
       +
       - [ ] Integration tests for XRPC endpoints

     

       140
       140
       +
       - [ ] Test rate limiting (per phone, per DID)

     

       141
       141
       +
       - [ ] Test signature verification (third-party client)

     

       142
       142
       +
       - [ ] Test PDS write-back

     

       143
       143
       +
       - [ ] Test phone hash collision detection

     

       144
       144
       +
       

     

       145
       145
       +
       ### Security Audit

     

       146
       146
       +
       - [ ] Verify OTP uses crypto/rand

     

       147
       147
       +
       - [ ] Verify constant-time code comparison (bcrypt)

     

       148
       148
       +
       - [ ] Verify rate limits are enforced

     

       149
       149
       +
       - [ ] Verify phone numbers never logged in plaintext

     

       150
       150
       +
       - [ ] Verify audit logs don't leak sensitive data

     

       151
       151
       +
       - [ ] Verify signatures can't be forged

     

       152
       152
       +
       - [ ] Test SMS provider failover/retry logic

     

       153
       153
       +
       

     

       154
       154
       +
       ## Security Considerations

     

       155
       155
       +
       

     

       156
       156
       +
       ### Rate Limits

     

       157
       157
       +
       - **Per Phone**: 3 requests/hour (prevents SMS spam to victim)

     

       158
       158
       +
       - **Per DID**: 5 requests/day (prevents user abuse)

     

       159
       159
       +
       

     

       160
       160
       +
       ### OTP Security

     

       161
       161
       +
       - **Length**: 6 digits (1M combinations)

     

       162
       162
       +
       - **Expiry**: 10 minutes

     

       163
       163
       +
       - **Max Attempts**: 3 (then must request new code)

     

       164
       164
       +
       - **Storage**: Bcrypt hashed (not reversible)

     

       165
       165
       +
       

     

       166
       166
       +
       ### Phone Hash Security

     

       167
       167
       +
       - **Algorithm**: HMAC-SHA256(phone, pepper)

     

       168
       168
       +
       - **Pepper**: 32-byte secret, environment variable

     

       169
       169
       +
       - **Purpose**: Prevent rainbow table attacks

     

       170
       170
       +
       - **Uniqueness**: One phone = one verified account

     

       171
       171
       +
       

     

       172
       172
       +
       ### Signature Security

     

       173
       173
       +
       - **Algorithm**: ECDSA P-256 (ES256)

     

       174
       174
       +
       - **Payload**: type + verifiedBy + verifiedAt + expiresAt + subjectDID

     

       175
       175
       +
       - **Verification**: Third-party clients fetch public key from DID document

     

       176
       176
       +
       

     

       177
       177
       +
       ## Annual Re-verification Flow

     

       178
       178
       +
       

     

       179
       179
       +
       1. **30 days before expiry**: Set `needsRenewal: true` in status API

     

       180
       180
       +
       2. **Show banner in app**: "Your verification expires soon, renew now"

     

       181
       181
       +
       3. **User re-verifies**: Same flow, new phone allowed

     

       182
       182
       +
       4. **Old verification**: Expires, badge removed from profile

     

       183
       183
       +
       

     

       184
       184
       +
       ## Phone Loss/Change Flow

     

       185
       185
       +
       

     

       186
       186
       +
       1. User reports "lost phone" in app

     

       187
       187
       +
       2. AppView removes verification from PDS profile

     

       188
       188
       +
       3. AppView deletes phone_hash from database

     

       189
       189
       +
       4. User verifies new phone number

     

       190
       190
       +
       5. Badge restored with new phone_hash

     

       191
       191
       +
       

     

       192
       192
       +
       ## Third-Party Client Integration

     

       193
       193
       +
       

     

       194
       194
       +
       ### Verifying Badges

     

       195
       195
       +
       ```javascript

     

       196
       196
       +
       // 1. Fetch user profile from PDS

     

       197
       197
       +
       const profileOwnerDID = 'did:plc:abc123'  // The DID whose profile you're viewing

     

       198
       198
       +
       const profile = await fetchProfileFromPDS(profileOwnerDID)

     

       199
       199
       +
       

     

       200
       200
       +
       // 2. Check for phone verification

     

       201
       201
       +
       const phoneVerification = profile.verifications?.find(v => v.type === 'phone')

     

       202
       202
       +
       if (!phoneVerification) {

     

       203
       203
       +
         // No phone verification

     

       204
       204
       +
         return false

     

       205
       205
       +
       }

     

       206
       206
       +
       

     

       207
       207
       +
       // 3. Fetch Coves DID document

     

       208
       208
       +
       const didDoc = await fetch('https://coves.social/.well-known/did.json').then(r => r.json())

     

       209
       209
       +
       const publicKey = didDoc.verificationMethod[0].publicKeyJwk

     

       210
       210
       +
       

     

       211
       211
       +
       // 4. Verify signature (CRITICAL: includes profileOwnerDID to prevent copying)

     

       212
       212
       +
       const payload = phoneVerification.type +

     

       213
       213
       +
                       phoneVerification.verifiedBy +

     

       214
       214
       +
                       phoneVerification.verifiedAt +

     

       215
       215
       +
                       phoneVerification.expiresAt +

     

       216
       216
       +
                       profileOwnerDID  // ← This binds verification to this specific user

     

       217
       217
       +
       

     

       218
       218
       +
       const isValid = await verifySignature(payload, phoneVerification.signature, publicKey)

     

       219
       219
       +
       

     

       220
       220
       +
       // 5. Check expiry

     

       221
       221
       +
       const expired = new Date(phoneVerification.expiresAt) < new Date()

     

       222
       222
       +
       

     

       223
       223
       +
       return isValid && !expired

     

       224
       224
       +
       

     

       225
       225
       +
       // If Alice tries to copy this verification to her profile, the signature verification

     

       226
       226
       +
       // will fail because her DID is different from the original subject DID in the payload

     

       227
       227
       +
       ```

     

       228
       228
       +
       

     

       229
       229
       +
       ## Monitoring & Observability

     

       230
       230
       +
       

     

       231
       231
       +
       ### Key Metrics

     

       232
       232
       +
       - SMS delivery rate (should be >99%)

     

       233
       233
       +
       - Verification completion rate (request → verify)

     

       234
       234
       +
       - Rate limit hit rate (should be low)

     

       235
       235
       +
       - Average time to verify

     

       236
       236
       +
       - Cost per verification

     

       237
       237
       +
       

     

       238
       238
       +
       ### Alerts

     

       239
       239
       +
       - SMS delivery failures spike

     

       240
       240
       +
       - Unusual rate limit hits (possible attack)

     

       241
       241
       +
       - Signature validation failures (bug or attack)

     

       242
       242
       +
       - PDS write failures

     

       243
       243
       +
       

     

       244
       244
       +
       ### Audit Log Queries

     

       245
       245
       +
       ```sql

     

       246
       246
       +
       -- Failed verification attempts by DID

     

       247
       247
       +
       SELECT did, COUNT(*) as failures

     

       248
       248
       +
       FROM phone_verification_audit_log

     

       249
       249
       +
       WHERE event_type = 'verification_failed'

     

       250
       250
       +
         AND created_at > NOW() - INTERVAL '24 hours'

     

       251
       251
       +
       GROUP BY did

     

       252
       252
       +
       HAVING COUNT(*) > 5;

     

       253
       253
       +
       

     

       254
       254
       +
       -- Rate limit hits (possible attack)

     

       255
       255
       +
       SELECT phone_hash, COUNT(*) as hits

     

       256
       256
       +
       FROM phone_verification_audit_log

     

       257
       257
       +
       WHERE event_type = 'rate_limit_hit'

     

       258
       258
       +
         AND created_at > NOW() - INTERVAL '1 hour'

     

       259
       259
       +
       GROUP BY phone_hash

     

       260
       260
       +
       ORDER BY hits DESC

     

       261
       261
       +
       LIMIT 10;

     

       262
       262
       +
       ```

     

       263
       263
       +
       

     

       264
       264
       +
       ## Cost Estimation

     

       265
       265
       +
       

     

       266
       266
       +
       ### Telnyx Pricing (US)

     

       267
       267
       +
       - **SMS**: $0.004/message

     

       268
       268
       +
       - **Monthly estimate**: 10,000 verifications = $40/month

     

       269
       269
       +
       - **Annual re-verification**: Ongoing cost, plan accordingly

     

       270
       270
       +
       

     

       271
       271
       +
       ### Comparison

     

       272
       272
       +
       - Twilio: $0.0079/message = $79/month (98% more expensive)

     

       273
       273
       +
       - AWS SNS: $0.0064/message = $64/month (60% more expensive)

     

       274
       274
       +
       

     

       275
       275
       +
       ## Future Enhancements

     

       276
       276
       +
       

     

       277
       277
       +
       ### v1.1 - Email Verification

     

       278
       278
       +
       - Same architecture, different `type: "email"`

     

       279
       279
       +
       - Reuse signature service

     

       280
       280
       +
       - Add email provider (e.g., AWS SES)

     

       281
       281
       +
       

     

       282
       282
       +
       ### v1.2 - Domain Verification

     

       283
       283
       +
       - Prove ownership of domain

     

       284
       284
       +
       - `type: "domain"`

     

       285
       285
       +
       - DNS TXT record validation

     

       286
       286
       +
       

     

       287
       287
       +
       ### v1.3 - Government ID

     

       288
       288
       +
       - KYC provider integration

     

       289
       289
       +
       - `type: "government_id"`

     

       290
       290
       +
       - Higher trust level

     

       291
       291
       +
       

     

       292
       292
       +
       ## Support

     

       293
       293
       +
       

     

       294
       294
       +
       For questions or issues:

     

       295
       295
       +
       - GitHub Issues: https://github.com/coves-social/coves/issues

     

       296
       296
       +
       - Discord: [your-discord-link]

     

       297
       297
       +
       - Email: support@coves.social

+178

docs/PHONE_VERIFICATION_SUMMARY.md

···

       1
       1
       +
       # Phone Verification Implementation Summary

     

       2
       2
       +
       

     

       3
       3
       +
       ## Quick Start

     

       4
       4
       +
       

     

       5
       5
       +
       We've implemented a **privacy-first, cryptographically-signed phone verification system** for Coves that:

     

       6
       6
       +
       

     

       7
       7
       +
       ✅ Keeps phone numbers **completely private** (never stored in plaintext)

     

       8
       8
       +
       ✅ Creates **portable verification badges** (works across third-party apps)

     

       9
       9
       +
       ✅ Uses **did:web DID** for cryptographic signing

     

       10
       10
       +
       ✅ Integrates with **Telnyx SMS** (50% cheaper than Twilio)

     

       11
       11
       +
       ✅ Supports **annual re-verification** and phone number changes

     

       12
       12
       +
       ✅ Includes **rate limiting** and **audit logging** for security

     

       13
       13
       +
       

     

       14
       14
       +
       ## Files Created

     

       15
       15
       +
       

     

       16
       16
       +
       ### Lexicons

     

       17
       17
       +
       - `internal/atproto/lexicon/social/coves/actor/profile.json` (updated)

     

       18
       18
       +
       - `internal/atproto/lexicon/social/coves/verification/requestPhone.json`

     

       19
       19
       +
       - `internal/atproto/lexicon/social/coves/verification/verifyPhone.json`

     

       20
       20
       +
       - `internal/atproto/lexicon/social/coves/verification/getStatus.json`

     

       21
       21
       +
       

     

       22
       22
       +
       ### Database

     

       23
       23
       +
       - `internal/db/migrations/005_create_phone_verification_tables.sql`

     

       24
       24
       +
       

     

       25
       25
       +
       ### Service Layer

     

       26
       26
       +
       - `internal/core/verification/interfaces.go`

     

       27
       27
       +
       - `internal/core/verification/service.go`

     

       28
       28
       +
       - `internal/core/verification/errors.go`

     

       29
       29
       +
       

     

       30
       30
       +
       ### SMS Provider

     

       31
       31
       +
       - `internal/sms/telnyx/client.go`

     

       32
       32
       +
       

     

       33
       33
       +
       ### Configuration

     

       34
       34
       +
       - `.env.example` (with all required environment variables)

     

       35
       35
       +
       - `.well-known/did.json` (DID document for signature verification)

     

       36
       36
       +
       

     

       37
       37
       +
       ### Documentation

     

       38
       38
       +
       - `docs/DID_SETUP.md` (How to set up the DID and keypair)

     

       39
       39
       +
       - `docs/PHONE_VERIFICATION_IMPLEMENTATION.md` (Complete implementation guide)

     

       40
       40
       +
       

     

       41
       41
       +
       ## SMS Provider Decision: Telnyx

     

       42
       42
       +
       

     

       43
       43
       +
       **Winner**: Telnyx

     

       44
       44
       +
       **Pricing**: $0.004/SMS (US) - 50% cheaper than Twilio

     

       45
       45
       +
       **Why**: Owned infrastructure, 10x throughput, free support, international coverage

     

       46
       46
       +
       

     

       47
       47
       +
       **Cost estimate**: 10,000 verifications/month = **$40/month**

     

       48
       48
       +
       

     

       49
       49
       +
       ## Architecture Summary

     

       50
       50
       +
       

     

       51
       51
       +
       ### How It Works

     

       52
       52
       +
       

     

       53
       53
       +
       1. **User requests verification** → AppView sends OTP via Telnyx

     

       54
       54
       +
       2. **User enters code** → AppView validates (max 3 attempts)

     

       55
       55
       +
       3. **AppView creates signed verification** using `did:web:coves.social` private key

     

       56
       56
       +
       4. **AppView writes to user's PDS** via `com.atproto.repo.putRecord` (OAuth)

     

       57
       57
       +
       5. **Badge appears on profile** → Third-party apps can verify signature

     

       58
       58
       +
       6. **AppView stores phone_hash** → Prevents duplicate verifications

     

       59
       59
       +
       

     

       60
       60
       +
       ### Privacy Guarantees

     

       61
       61
       +
       

     

       62
       62
       +
       | Data | Stored Where | Format |

     

       63
       63
       +
       |------|--------------|--------|

     

       64
       64
       +
       | Phone number | **NOWHERE** | Never stored |

     

       65
       65
       +
       | Phone hash | AppView DB | HMAC-SHA256(phone, pepper) |

     

       66
       66
       +
       | OTP code | AppView DB (temp) | Bcrypt hash, 10min TTL |

     

       67
       67
       +
       | Verification badge | User's PDS | Signed JSON (no phone data) |

     

       68
       68
       +
       

     

       69
       69
       +
       ### Security Features

     

       70
       70
       +
       

     

       71
       71
       +
       - ✅ **Rate limits**: 3/hour per phone, 5/day per user

     

       72
       72
       +
       - ✅ **OTP expiry**: 10 minutes

     

       73
       73
       +
       - ✅ **Max attempts**: 3 per OTP request

     

       74
       74
       +
       - ✅ **Cryptographic signatures**: ECDSA P-256 (can't be forged)

     

       75
       75
       +
       - ✅ **Audit logging**: All events tracked for fraud detection

     

       76
       76
       +
       - ✅ **Constant-time comparison**: Prevents timing attacks

     

       77
       77
       +
       

     

       78
       78
       +
       ## Next Steps to Deploy

     

       79
       79
       +
       

     

       80
       80
       +
       ### 1. Generate Secrets

     

       81
       81
       +
       ```bash

     

       82
       82
       +
       # DID signing keypair

     

       83
       83
       +
       openssl ecparam -name prime256v1 -genkey -noout -out verification-key.pem

     

       84
       84
       +
       export VERIFICATION_PRIVATE_KEY="$(cat verification-key.pem | base64 -w 0)"

     

       85
       85
       +
       

     

       86
       86
       +
       # Phone hash pepper

     

       87
       87
       +
       export PHONE_HASH_PEPPER="$(openssl rand -base64 32)"

     

       88
       88
       +
       ```

     

       89
       89
       +
       

     

       90
       90
       +
       ### 2. Configure Telnyx

     

       91
       91
       +
       - Sign up: https://telnyx.com

     

       92
       92
       +
       - Get API key + messaging profile ID

     

       93
       93
       +
       - Purchase phone number

     

       94
       94
       +
       

     

       95
       95
       +
       ### 3. Update DID Document

     

       96
       96
       +
       - Extract public key from `verification-key.pem` (convert to JWK)

     

       97
       97
       +
       - Update `.well-known/did.json` with actual coordinates

     

       98
       98
       +
       - Deploy to `https://coves.social/.well-known/did.json`

     

       99
       99
       +
       

     

       100
       100
       +
       ### 4. Implement Missing Components

     

       101
       101
       +
       - [ ] `PhoneHashProvider` (HMAC-SHA256 implementation)

     

       102
       102
       +
       - [ ] `SignatureService` (ECDSA P-256 signing)

     

       103
       103
       +
       - [ ] `PDSWriter` (write verifications to PDS via OAuth)

     

       104
       104
       +
       - [ ] `VerificationRepository` (PostgreSQL implementation)

     

       105
       105
       +
       - [ ] XRPC handlers (routes + error mapping)

     

       106
       106
       +
       - [ ] Background cleanup job (expired OTP requests)

     

       107
       107
       +
       

     

       108
       108
       +
       ### 5. Frontend Integration

     

       109
       109
       +
       - [ ] Phone input screen (E.164 validation)

     

       110
       110
       +
       - [ ] OTP entry screen

     

       111
       111
       +
       - [ ] Verification badge display

     

       112
       112
       +
       - [ ] Re-verification flow

     

       113
       113
       +
       

     

       114
       114
       +
       ## Questions Answered

     

       115
       115
       +
       

     

       116
       116
       +
       ### Q: Where is the verification badge stored?

     

       117
       117
       +
       **A**: In the user's PDS profile (`social.coves.actor.profile` record), in the `verifications` array. Third-party apps can read it directly from the PDS.

     

       118
       118
       +
       

     

       119
       119
       +
       ### Q: Can users fake the verification?

     

       120
       120
       +
       **A**: No. The badge includes a cryptographic signature that third-party apps can verify using Coves' public key from the DID document.

     

       121
       121
       +
       

     

       122
       122
       +
       ### Q: What if someone forks Coves?

     

       123
       123
       +
       **A**: They set `VERIFICATION_SERVICE_DID=did:web:their-domain.com` and generate their own keypair. The system is fully self-hostable.

     

       124
       124
       +
       

     

       125
       125
       +
       ### Q: How do third-party apps verify the badge?

     

       126
       126
       +
       **A**:

     

       127
       127
       +
       1. Fetch the DID document from `https://coves.social/.well-known/did.json`

     

       128
       128
       +
       2. Extract the public key from `verificationMethod[0].publicKeyJwk`

     

       129
       129
       +
       3. **CRITICAL**: Verify the signature includes the **profile owner's DID** in the payload

     

       130
       130
       +
       4. Reconstruct payload: `type + verifiedBy + verifiedAt + expiresAt + profileOwnerDID`

     

       131
       131
       +
       5. Verify signature matches payload

     

       132
       132
       +
       

     

       133
       133
       +
       **Security Note**: The signature MUST include the subject DID. This prevents users from copying someone else's verification to their profile (the signature won't match because the DID is different).

     

       134
       134
       +
       

     

       135
       135
       +
       ### Q: What happens on phone loss?

     

       136
       136
       +
       **A**: User reports lost phone → AppView removes verification from PDS → User verifies new number → Badge restored.

     

       137
       137
       +
       

     

       138
       138
       +
       ### Q: Why annual re-verification?

     

       139
       139
       +
       **A**: Ensures active users, detects account takeovers, gives a yearly touchpoint for security checks.

     

       140
       140
       +
       

     

       141
       141
       +
       ## File Locations Reference

     

       142
       142
       +
       

     

       143
       143
       +
       ```

     

       144
       144
       +
       Coves/

     

       145
       145
       +
       ├── .env.example                                        # Environment config template

     

       146
       146
       +
       ├── .well-known/

     

       147
       147
       +
       │   └── did.json                                       # DID document (serves at /.well-known/did.json)

     

       148
       148
       +
       ├── docs/

     

       149
       149
       +
       │   ├── DID_SETUP.md                                   # DID keypair setup guide

     

       150
       150
       +
       │   ├── PHONE_VERIFICATION_IMPLEMENTATION.md           # Complete implementation guide

     

       151
       151
       +
       │   └── PHONE_VERIFICATION_SUMMARY.md                  # This file

     

       152
       152
       +
       ├── internal/

     

       153
       153
       +
       │   ├── atproto/lexicon/social/coves/

     

       154
       154
       +
       │   │   ├── actor/profile.json                         # Updated with verifications array

     

       155
       155
       +
       │   │   └── verification/

     

       156
       156
       +
       │   │       ├── requestPhone.json                      # XRPC: Request OTP

     

       157
       157
       +
       │   │       ├── verifyPhone.json                       # XRPC: Verify OTP

     

       158
       158
       +
       │   │       └── getStatus.json                         # XRPC: Get verification status

     

       159
       159
       +
       │   ├── core/verification/

     

       160
       160
       +
       │   │   ├── interfaces.go                              # Service contracts

     

       161
       161
       +
       │   │   ├── service.go                                 # Verification logic

     

       162
       162
       +
       │   │   └── errors.go                                  # Domain errors

     

       163
       163
       +
       │   ├── db/migrations/

     

       164
       164
       +
       │   │   └── 005_create_phone_verification_tables.sql   # Database schema

     

       165
       165
       +
       │   └── sms/telnyx/

     

       166
       166
       +
       │       └── client.go                                  # Telnyx API integration

     

       167
       167
       +
       ```

     

       168
       168
       +
       

     

       169
       169
       +
       ## Resources

     

       170
       170
       +
       

     

       171
       171
       +
       - **Telnyx Docs**: https://developers.telnyx.com/docs/api/v2/messaging

     

       172
       172
       +
       - **DID Spec**: https://www.w3.org/TR/did-core/

     

       173
       173
       +
       - **atProto Specs**: https://atproto.com/specs/

     

       174
       174
       +
       - **E.164 Format**: https://en.wikipedia.org/wiki/E.164

     

       175
       175
       +
       

     

       176
       176
       +
       ## Contact

     

       177
       177
       +
       

     

       178
       178
       +
       Questions? Open an issue or reach out on Discord!

+229

docs/VERIFICATION_SECURITY.md

···

       1
       1
       +
       # Verification Security Model

     

       2
       2
       +
       

     

       3
       3
       +
       ## Attack Prevention: Signature Copying

     

       4
       4
       +
       

     

       5
       5
       +
       ### The Threat

     

       6
       6
       +
       **Question**: What if Bob copies Alice's verification to his profile?

     

       7
       7
       +
       

     

       8
       8
       +
       ```json

     

       9
       9
       +
       // Alice's profile (did:plc:alice123)

     

       10
       10
       +
       {

     

       11
       11
       +
         "verifications": [

     

       12
       12
       +
           {

     

       13
       13
       +
             "type": "phone",

     

       14
       14
       +
             "verifiedBy": "did:web:coves.social",

     

       15
       15
       +
             "verifiedAt": "2025-01-15T10:00:00Z",

     

       16
       16
       +
             "expiresAt": "2026-01-15T10:00:00Z",

     

       17
       17
       +
             "signature": "abc123..."

     

       18
       18
       +
           }

     

       19
       19
       +
         ]

     

       20
       20
       +
       }

     

       21
       21
       +
       

     

       22
       22
       +
       // Bob copies this to his profile (did:plc:bob456)

     

       23
       23
       +
       // Will this work? NO!

     

       24
       24
       +
       ```

     

       25
       25
       +
       

     

       26
       26
       +
       ### The Defense

     

       27
       27
       +
       

     

       28
       28
       +
       The signature is created over this payload:

     

       29
       29
       +
       ```

     

       30
       30
       +
       type + verifiedBy + verifiedAt + expiresAt + subjectDID

     

       31
       31
       +
       ```

     

       32
       32
       +
       

     

       33
       33
       +
       **Critical**: `subjectDID` is the DID of the person being verified.

     

       34
       34
       +
       

     

       35
       35
       +
       ### Example

     

       36
       36
       +
       

     

       37
       37
       +
       **Alice's signature payload:**

     

       38
       38
       +
       ```

     

       39
       39
       +
       "phone" + "did:web:coves.social" + "2025-01-15T10:00:00Z" + "2026-01-15T10:00:00Z" + "did:plc:alice123"

     

       40
       40
       +
       → Signature: "abc123..."

     

       41
       41
       +
       ```

     

       42
       42
       +
       

     

       43
       43
       +
       **Bob tries to use Alice's verification:**

     

       44
       44
       +
       ```

     

       45
       45
       +
       Bob's DID: did:plc:bob456

     

       46
       46
       +
       Alice's signature: "abc123..."

     

       47
       47
       +
       

     

       48
       48
       +
       Third-party app verifies:

     

       49
       49
       +
       payload = "phone" + "did:web:coves.social" + "2025-01-15T10:00:00Z" + "2026-01-15T10:00:00Z" + "did:plc:bob456"

     

       50
       50
       +
       verify(payload, "abc123...", publicKey) → FALSE ❌

     

       51
       51
       +
       

     

       52
       52
       +
       The signature doesn't match because Bob's DID is different from Alice's DID!

     

       53
       53
       +
       ```

     

       54
       54
       +
       

     

       55
       55
       +
       ### Implementation

     

       56
       56
       +
       

     

       57
       57
       +
       **Service (when creating signature):**

     

       58
       58
       +
       ```go

     

       59
       59
       +
       // service.go:216-222

     

       60
       60
       +
       verificationData := &VerificationData{

     

       61
       61
       +
           Type:       "phone",

     

       62
       62
       +
           VerifiedBy: s.signer.GetVerifierDID(),

     

       63
       63
       +
           VerifiedAt: now,

     

       64
       64
       +
           ExpiresAt:  expiresAt,

     

       65
       65
       +
           SubjectDID: did,  // ← This binds it to the user

     

       66
       66
       +
       }

     

       67
       67
       +
       ```

     

       68
       68
       +
       

     

       69
       69
       +
       **Third-party app (when verifying):**

     

       70
       70
       +
       ```javascript

     

       71
       71
       +
       // Reconstruct the EXACT same payload

     

       72
       72
       +
       const payload = verification.type +

     

       73
       73
       +
                       verification.verifiedBy +

     

       74
       74
       +
                       verification.verifiedAt +

     

       75
       75
       +
                       verification.expiresAt +

     

       76
       76
       +
                       profileOwnerDID  // ← MUST use the profile owner's DID

     

       77
       77
       +
       

     

       78
       78
       +
       // Verify signature

     

       79
       79
       +
       const isValid = verifyECDSA(payload, verification.signature, publicKey)

     

       80
       80
       +
       ```

     

       81
       81
       +
       

     

       82
       82
       +
       ## Other Attack Vectors

     

       83
       83
       +
       

     

       84
       84
       +
       ### 1. Replay Attack (Using old verification)

     

       85
       85
       +
       **Defense**: Expiry timestamp (`expiresAt`) is part of signed payload

     

       86
       86
       +
       - Clients check `expiresAt < now()` → reject

     

       87
       87
       +
       - Annual re-verification ensures freshness

     

       88
       88
       +
       

     

       89
       89
       +
       ### 2. Forged Signature

     

       90
       90
       +
       **Defense**: ECDSA P-256 signature with private key known only to Coves

     

       91
       91
       +
       - Attacker would need Coves' private key

     

       92
       92
       +
       - Private key stored in secure environment (secrets manager)

     

       93
       93
       +
       - Can't be brute-forced (256-bit security)

     

       94
       94
       +
       

     

       95
       95
       +
       ### 3. Man-in-the-Middle (DID document swap)

     

       96
       96
       +
       **Defense**: HTTPS + optional DID pinning

     

       97
       97
       +
       - DID document served over HTTPS

     

       98
       98
       +
       - Clients can pin Coves' DID public key in app

     

       99
       99
       +
       - DNS/TLS security prevents MITM

     

       100
       100
       +
       

     

       101
       101
       +
       ### 4. Verification Badge Removal

     

       102
       102
       +
       **Defense**: User controls their own PDS

     

       103
       103
       +
       - Only the user (or authorized apps with OAuth) can modify their profile

     

       104
       104
       +
       - AppView writes via OAuth (with user consent)

     

       105
       105
       +
       - Other apps can't remove verifications without permission

     

       106
       106
       +
       

     

       107
       107
       +
       ### 5. Phone Number Reuse (Carrier recycling)

     

       108
       108
       +
       **Defense**: Expiry + re-verification

     

       109
       109
       +
       - Verifications expire after 1 year

     

       110
       110
       +
       - If carrier recycles number to new person, old verification expires

     

       111
       111
       +
       - New person must verify to get new badge

     

       112
       112
       +
       

     

       113
       113
       +
       ### 6. SMS Interception (SIM swap)

     

       114
       114
       +
       **Defense**: Rate limiting + audit logging

     

       115
       115
       +
       - Max 3 OTP requests per phone per hour

     

       116
       116
       +
       - Audit logs track suspicious patterns

     

       117
       117
       +
       - Future: Add 2FA backup methods (email, authenticator)

     

       118
       118
       +
       

     

       119
       119
       +
       ### 7. Phone Hash Rainbow Table

     

       120
       120
       +
       **Defense**: HMAC with secret pepper

     

       121
       121
       +
       ```go

     

       122
       122
       +
       phoneHash = HMAC-SHA256(phoneNumber, secretPepper)

     

       123
       123
       +
       ```

     

       124
       124
       +
       - Even if DB is leaked, attacker can't reverse hashes without pepper

     

       125
       125
       +
       - Pepper stored separately (environment variable)

     

       126
       126
       +
       - Prevents bulk phone number enumeration

     

       127
       127
       +
       

     

       128
       128
       +
       ## Verification Lifecycle Security

     

       129
       129
       +
       

     

       130
       130
       +
       ### Creation

     

       131
       131
       +
       1. ✅ User authenticates with OAuth

     

       132
       132
       +
       2. ✅ AppView verifies phone ownership (OTP)

     

       133
       133
       +
       3. ✅ AppView creates signature (includes subject DID)

     

       134
       134
       +
       4. ✅ AppView writes to user's PDS (OAuth scope)

     

       135
       135
       +
       5. ✅ AppView stores phone_hash (duplicate prevention)

     

       136
       136
       +
       

     

       137
       137
       +
       ### Validation (Third-party apps)

     

       138
       138
       +
       1. ✅ Fetch user's profile from PDS

     

       139
       139
       +
       2. ✅ Extract verification from `verifications` array

     

       140
       140
       +
       3. ✅ Fetch Coves DID document (public key)

     

       141
       141
       +
       4. ✅ Reconstruct payload (including profile owner DID)

     

       142
       142
       +
       5. ✅ Verify signature matches

     

       143
       143
       +
       6. ✅ Check expiry timestamp

     

       144
       144
       +
       

     

       145
       145
       +
       ### Revocation

     

       146
       146
       +
       1. ✅ User loses phone → requests revocation

     

       147
       147
       +
       2. ✅ AppView removes verification from PDS

     

       148
       148
       +
       3. ✅ AppView deletes phone_hash from DB

     

       149
       149
       +
       4. ✅ Third-party apps see no verification (fetching latest from PDS)

     

       150
       150
       +
       

     

       151
       151
       +
       ## did:web Security

     

       152
       152
       +
       

     

       153
       153
       +
       ### Why `.well-known/did.json` is Safe

     

       154
       154
       +
       

     

       155
       155
       +
       **Q**: Can someone just change the DID document?

     

       156
       156
       +
       **A**: No, because:

     

       157
       157
       +
       

     

       158
       158
       +
       1. **Domain ownership**: Only owner of `coves.social` can serve files at `https://coves.social/.well-known/did.json`

     

       159
       159
       +
       2. **HTTPS**: TLS prevents MITM attacks

     

       160
       160
       +
       3. **Key rotation**: If private key compromised, we rotate (keep old key for 30 days for existing verifications)

     

       161
       161
       +
       

     

       162
       162
       +
       ### Alternative: DNS TXT Record

     

       163
       163
       +
       We could also add a DNS TXT record for extra verification:

     

       164
       164
       +
       ```

     

       165
       165
       +
       _did.coves.social TXT "did=did:web:coves.social key=<public-key-fingerprint>"

     

       166
       166
       +
       ```

     

       167
       167
       +
       This provides defense-in-depth (DNS + HTTPS both need to be compromised).

     

       168
       168
       +
       

     

       169
       169
       +
       ## Comparison to Other Verification Systems

     

       170
       170
       +
       

     

       171
       171
       +
       ### Twitter Blue (Centralized)

     

       172
       172
       +
       - ❌ Phone stored on Twitter servers

     

       173
       173
       +
       - ❌ Not portable (can't take verification to other apps)

     

       174
       174
       +
       - ❌ Twitter controls badge (can remove)

     

       175
       175
       +
       - ✅ Simple to verify (just trust Twitter)

     

       176
       176
       +
       

     

       177
       177
       +
       ### Bluesky Verification (Domain-based)

     

       178
       178
       +
       - ✅ Decentralized (DNS TXT record)

     

       179
       179
       +
       - ✅ Portable (works across apps)

     

       180
       180
       +
       - ❌ Only works for domain owners

     

       181
       181
       +
       - ❌ No phone verification

     

       182
       182
       +
       

     

       183
       183
       +
       ### Coves Verification (Hybrid)

     

       184
       184
       +
       - ✅ Privacy-first (phone never stored)

     

       185
       185
       +
       - ✅ Portable (PDS-stored, cryptographically signed)

     

       186
       186
       +
       - ✅ Works for non-domain owners

     

       187
       187
       +
       - ✅ Third-party verifiable (public key in DID document)

     

       188
       188
       +
       - ✅ User-controlled (badge on their PDS)

     

       189
       189
       +
       - ⚠️ Requires crypto verification (more complex for clients)

     

       190
       190
       +
       

     

       191
       191
       +
       ## Security Checklist

     

       192
       192
       +
       

     

       193
       193
       +
       When implementing, ensure:

     

       194
       194
       +
       

     

       195
       195
       +
       - [ ] Private key stored securely (secrets manager, not in code)

     

       196
       196
       +
       - [ ] Phone hash pepper never changes (backup safely)

     

       197
       197
       +
       - [ ] OTP generated with `crypto/rand` (not `math/rand`)

     

       198
       198
       +
       - [ ] OTP comparison is constant-time (bcrypt)

     

       199
       199
       +
       - [ ] Subject DID included in signature payload

     

       200
       200
       +
       - [ ] Third-party apps verify signature correctly

     

       201
       201
       +
       - [ ] Rate limits enforced at network edge

     

       202
       202
       +
       - [ ] Audit logs don't leak phone numbers

     

       203
       203
       +
       - [ ] HTTPS enforced for DID document

     

       204
       204
       +
       - [ ] PDS writes use OAuth (user consent)

     

       205
       205
       +
       

     

       206
       206
       +
       ## Future Enhancements

     

       207
       207
       +
       

     

       208
       208
       +
       ### 1. Multi-factor Verification

     

       209
       209
       +
       Require 2+ verification types:

     

       210
       210
       +
       - Phone + Email

     

       211
       211
       +
       - Phone + Domain

     

       212
       212
       +
       - Government ID + Phone

     

       213
       213
       +
       

     

       214
       214
       +
       ### 2. Verification Revocation List

     

       215
       215
       +
       Publish revoked verifications at `https://coves.social/.well-known/revocations.json`

     

       216
       216
       +
       - Third-party apps can check if verification was revoked

     

       217
       217
       +
       - User privacy preserved (DID hash, not full DID)

     

       218
       218
       +
       

     

       219
       219
       +
       ### 3. Hardware Security Module (HSM)

     

       220
       220
       +
       Store signing key in HSM for production:

     

       221
       221
       +
       - AWS CloudHSM

     

       222
       222
       +
       - Google Cloud KMS

     

       223
       223
       +
       - Azure Key Vault

     

       224
       224
       +
       

     

       225
       225
       +
       Prevents key extraction even with server compromise.

     

       226
       226
       +
       

     

       227
       227
       +
       ## Questions?

     

       228
       228
       +
       

     

       229
       229
       +
       Open an issue or ask on Discord!