DID Setup for Coves Verification Service#

Overview#

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.

Generating the Verification Keypair#

# Generate P-256 EC keypair for signing verifications
openssl ecparam -name prime256v1 -genkey -noout -out verification-key.pem

# Extract public key in JWK format
# You'll need to convert this to JWK format for the DID document
openssl ec -in verification-key.pem -pubout -out verification-key-pub.pem

Converting to JWK Format#

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

• Go: github.com/lestrrat-go/jwx/v2/jwk
• Node.js: jose library
• Online: https://8gwifi.org/jwkconvertfunctions.jsp (for dev only)

Updating the DID Document#

1. Generate the keypair
2. Extract the public key JWK (x, y coordinates)
3. Update .well-known/did.json with the actual coordinates
4. Store the private key securely (environment variable or secrets manager)

Serving the DID Document#

The DID document must be served at:

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

With headers:

Content-Type: application/json
Access-Control-Allow-Origin: *

Environment Configuration#

DO NOT commit secrets to git!

Add to your .env file:

# DID for your instance (change coves.social to your domain)
VERIFICATION_SERVICE_DID=did:web:coves.social

# Private key (base64-encoded or plain PEM)
VERIFICATION_PRIVATE_KEY="$(cat verification-key.pem | base64 -w 0)"

In production, use a secrets manager:

• AWS Secrets Manager
• HashiCorp Vault
• Google Secret Manager

For forked deployments: If you're deploying your own instance at myapp.com, update:

1. VERIFICATION_SERVICE_DID=did:web:myapp.com
2. Serve DID document at https://myapp.com/.well-known/did.json
3. Update verificationMethod[0].id to use your domain

Verifying Signatures (Third-Party Clients)#

Third-party clients can verify phone verifications by:

1. Fetch DID document: https://coves.social/.well-known/did.json
2. Extract public key from verificationMethod[0].publicKeyJwk
3. Verify signature over verification data:

   payload = type + verifiedBy + verifiedAt + expiresAt + subjectDID
   verify(payload, signature, publicKey)
   

Key Rotation#

When rotating keys:

1. Generate new keypair
2. Add new key to verificationMethod array with new ID (#verification-key-2)
3. Keep old key for 30 days to allow verification of existing tokens
4. Update signing code to use new key
5. After 30 days, remove old key from DID document

Testing#

# Verify DID document is valid
curl https://coves.social/.well-known/did.json | jq .

# Should return valid JSON with your public key