bretton.dev / coves
A community based topic aggregation platform built on atproto
fork atom

docs(config): add HS256_ISSUERS configuration for JWT auth

Document the dual JWT verification methods (HS256 + ES256) in environment
configuration files:

- HS256: For your own PDS (fast, shared secret, no network calls)
- ES256: For federated users (DID resolution, works with any PDS)

Updates:
- .env.dev: Add HS256_ISSUERS for local development
- .env.prod.example: Add JWT Authentication section with documentation
- docker-compose.prod.yml: Pass PDS_JWT_SECRET and HS256_ISSUERS to appview

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

bretton.dev 2cf2da20 69c97ebd

options
unified split
Changed files
+39
.env.dev
.env.prod.example
docker-compose.prod.yml
+5
.env.dev 
···

       
152

       
 

       
# When false, verifies JWT signature against issuer's JWKS


     

       
153

       
 

       
AUTH_SKIP_VERIFY=true


     

       
154

       
 

       



     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       
155

       
 

       
# Logging


     

       
156

       
 

       
LOG_LEVEL=debug


     

       
157

       
 

       
LOG_ENABLED=true


     
···

       
152

       
 

       
# When false, verifies JWT signature against issuer's JWKS


     

       
153

       
 

       
AUTH_SKIP_VERIFY=true


     

       
154

       
 

       



     

       
155

       
+

       
# HS256 Issuers: PDSes allowed to use HS256 (shared secret) authentication


     

       
156

       
+

       
# Must share PDS_JWT_SECRET with Coves instance. External PDSes use ES256 via DID resolution.


     

       
157

       
+

       
# For local dev, allow the local PDS or turn AUTH_SKIP_VERIFY = true


     

       
158

       
+

       
HS256_ISSUERS=http://localhost:3001


     

       
159

       
+

       



     

       
160

       
 

       
# Logging


     

       
161

       
 

       
LOG_LEVEL=debug


     

       
162

       
 

       
LOG_ENABLED=true
+28
.env.prod.example 
···

       
27

       
 

       
# PDS_EMAIL_FROM_ADDRESS=noreply@coves.me


     

       
28

       
 

       



     

       
29

       
 

       
# =============================================================================


     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       
30

       
 

       
# AppView OAuth (for mobile app authentication)


     

       
31

       
 

       
# =============================================================================


     

       
32

       
 

       
OAUTH_CLIENT_ID=https://coves.social/client-metadata.json


     
···

       
27

       
 

       
# PDS_EMAIL_FROM_ADDRESS=noreply@coves.me


     

       
28

       
 

       



     

       
29

       
 

       
# =============================================================================


     

       
30

       
+

       
# JWT Authentication


     

       
31

       
+

       
# =============================================================================


     

       
32

       
+

       
# Coves supports two JWT verification methods:


     

       
33

       
+

       
#


     

       
34

       
+

       
# 1. HS256 (shared secret) - For your own PDS


     

       
35

       
+

       
#    - Fast, no network calls needed


     

       
36

       
+

       
#    - Requires shared PDS_JWT_SECRET


     

       
37

       
+

       
#    - Only for PDSes you control


     

       
38

       
+

       
#


     

       
39

       
+

       
# 2. ES256 (DID resolution) - For federated users


     

       
40

       
+

       
#    - Works with any PDS (bsky.social, etc.)


     

       
41

       
+

       
#    - Resolves user's DID document to get public key


     

       
42

       
+

       
#    - No shared secret needed


     

       
43

       
+

       
#


     

       
44

       
+

       
# HS256_ISSUERS: Comma-separated list of PDS URLs allowed to use HS256


     

       
45

       
+

       
# These PDSes MUST share the same PDS_JWT_SECRET with Coves


     

       
46

       
+

       
# Example: HS256_ISSUERS=https://pds.coves.social,https://pds.example.com


     

       
47

       
+

       
HS256_ISSUERS=https://pds.coves.me


     

       
48

       
+

       



     

       
49

       
+

       
# PLC Directory URL for DID resolution (optional)


     

       
50

       
+

       
# Defaults to https://plc.directory if not set


     

       
51

       
+

       
# PLC_DIRECTORY_URL=https://plc.directory


     

       
52

       
+

       



     

       
53

       
+

       
# Skip JWT signature verification (DEVELOPMENT ONLY!)


     

       
54

       
+

       
# Set to false in production for proper security


     

       
55

       
+

       
AUTH_SKIP_VERIFY=false


     

       
56

       
+

       



     

       
57

       
+

       
# =============================================================================


     

       
58

       
 

       
# AppView OAuth (for mobile app authentication)


     

       
59

       
 

       
# =============================================================================


     

       
60

       
 

       
OAUTH_CLIENT_ID=https://coves.social/client-metadata.json
+6
docker-compose.prod.yml 
···

       
96

       
 

       
      # Cursor encryption for pagination


     

       
97

       
 

       
      CURSOR_SECRET: ${CURSOR_SECRET}


     

       
98

       
 

       



     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       

       

       
     

       
99

       
 

       
      # Restrict community creation to instance DID only


     

       
100

       
 

       
      COMMUNITY_CREATORS: did:web:coves.social


     

       
101

       
 

       
    networks:


     
···

       
96

       
 

       
      # Cursor encryption for pagination


     

       
97

       
 

       
      CURSOR_SECRET: ${CURSOR_SECRET}


     

       
98

       
 

       



     

       
99

       
+

       
      # PDS JWT secret for verifying HS256 tokens from the PDS


     

       
100

       
+

       
      # Must match the PDS_JWT_SECRET configured on the PDS


     

       
101

       
+

       
      PDS_JWT_SECRET: ${PDS_JWT_SECRET}


     

       
102

       
+

       
      # Whitelist PDS issuer(s) allowed to use HS256 (no kid)


     

       
103

       
+

       
      HS256_ISSUERS: ${HS256_ISSUERS}


     

       
104

       
+

       



     

       
105

       
 

       
      # Restrict community creation to instance DID only


     

       
106

       
 

       
      COMMUNITY_CREATORS: did:web:coves.social


     

       
107

       
 

       
    networks: