# 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

```bash
# 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:
```bash
# 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

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

# Should return valid JSON with your public key
```