daily-notification-plugin/test-apps/daily-notification-test/INVESTIGATION_JWT_ALGORITHM.md

JWT Algorithm Investigation Guide

Created: 2025-10-31
Purpose: Systematically investigate which JWT signing algorithm endorser-ch and TimeSafari actually use

---

Investigation Checklist

Phase 1: TimeSafari Repository (Most Authoritative)

Repository: ssh://git@173.199.124.46:222/trent_larson/crowd-funder-for-time-pwa.git

Step 1: Find createEndorserJwtForDid Function

# Clone or navigate to the repository
cd /path/to/crowd-funder-for-time-pwa

# Search for the function
grep -r "createEndorserJwtForDid" .
grep -r "createEndorserJWT" .
grep -r "createEndorser.*JWT" .

What to look for:

• Function implementation showing how JWT is generated
• Import statements (e.g., did-jwt, jsonwebtoken, jose, etc.)
• Algorithm parameter (e.g., alg: 'HS256', algorithm: 'HS256', etc.)
• Key/secret usage (shared secret vs DID private key)

Step 2: Find Endpoint Usage

# Search for endpoint usage
grep -r "plansLastUpdatedBetween" .
grep -r "/api/v2/report" .

What to look for:

• How the JWT is attached to requests (Authorization header)
• What function generates the JWT for this endpoint
• Any configuration or secret management

Step 3: Check JWT Generation Code

Files to examine:

• Any files matching *jwt*.ts, *jwt*.js, *auth*.ts, *auth*.js
• Configuration files (.env, config/*.ts, src/config/*.ts)
• API client files that call endorser endpoints

Key questions:

1. Does it use a shared secret (string) or DID private key?
2. What library is used? (jsonwebtoken, did-jwt, jose, etc.)
3. What algorithm is specified in the code?

---

Phase 2: endorser-ch Repository (Server-Side Verification)

Repository: https://github.com/trentlarson/endorser-ch

Step 1: Find Endpoint Handler

# Clone or navigate to the repository
cd /path/to/endorser-ch

# Search for endpoint handler
grep -r "plansLastUpdatedBetween" .
grep -r "/api/v2/report" .

Files likely to contain:

• src/server.js or server/server.js
• src/routes.js or routes/*.js
• src/api/ or src/controllers/

Step 2: Find Authentication Middleware

# Search for JWT verification
grep -r "verifyJWT" .
grep -r "verify.*JWT" .
grep -r "Authorization.*Bearer" .
grep -r "did-jwt" .
grep -r "jsonwebtoken" .

What to look for:

• Middleware that processes Authorization: Bearer {token} header
• JWT verification logic
• Algorithm used for verification
• Secret/key used for verification

Step 3: Check Configuration for JWT Secret

# Search for JWT secret configuration
grep -r "JWT_SECRET" .
grep -r "API_SECRET" .
grep -r "jwtSecret" .
grep -r "jwt.*secret" -i .

Files to check:

• .env files
• config/*.js or conf/*.js
• package.json (for dependencies)

Key questions:

1. Is there a JWT_SECRET environment variable?
2. Does it use did-jwt.verifyJWT() with DID resolution?
3. Or does it use jsonwebtoken.verify() with a shared secret?

---

Expected Findings & Decision Matrix

Scenario A: HS256 with Shared Secret ✅ (Most Likely)

Indicators:

• ✅ TimeSafari code uses jsonwebtoken.sign() or similar with a secret string
• ✅ endorser-ch uses jsonwebtoken.verify() or similar with a secret
• ✅ Environment variable JWT_SECRET exists
• ✅ Code explicitly sets algorithm: 'HS256' or alg: 'HS256'

Action: Our current HMAC-SHA256 implementation is CORRECT

Scenario B: DID-based (ES256K) ⚠️

Indicators:

• ⚠️ TimeSafari code uses did-jwt.createJWT() or Veramo JWT creation
• ⚠️ endorser-ch uses did-jwt.verifyJWT() with DID resolver
• ⚠️ Code uses Ethereum private keys or DID document keys
• ⚠️ No shared secret configuration found

Action: Need to implement DID-based signing with ES256K algorithm

Scenario C: Hybrid Approach 🔄

Indicators:

• 🔄 Different algorithms for different endpoints
• 🔄 API auth uses HS256, but claim verification uses DID-based
• 🔄 Multiple authentication methods supported

Action: Use HS256 for /api/v2/report/plansLastUpdatedBetween endpoint

---

Investigation Commands Summary

TimeSafari Repository Investigation

cd /path/to/crowd-funder-for-time-pwa

# Find JWT generation
grep -r "createEndorserJwtForDid\|createEndorserJWT" . --include="*.ts" --include="*.js"

# Find endpoint usage
grep -r "plansLastUpdatedBetween" . --include="*.ts" --include="*.js"

# Check for JWT libraries
grep -r "jsonwebtoken\|did-jwt\|jose" package.json
grep -r "from.*jsonwebtoken\|from.*did-jwt\|import.*jose" . --include="*.ts" --include="*.js"

# Check for secret usage
grep -r "jwtSecret\|JWT_SECRET\|shared.*secret" . --include="*.ts" --include="*.js" -i

endorser-ch Repository Investigation

cd /path/to/endorser-ch

# Find endpoint handler
grep -r "plansLastUpdatedBetween" . --include="*.js" --include="*.ts"

# Find authentication middleware
grep -r "Authorization.*Bearer\|verifyJWT\|verify.*JWT" . --include="*.js" --include="*.ts"

# Check for JWT libraries
grep -r "jsonwebtoken\|did-jwt\|jose" package.json

# Check for secret configuration
grep -r "JWT_SECRET\|API_SECRET\|jwt.*secret" . -i --include="*.js" --include="*.env*"

---

Documentation References to Review

TimeSafari Repository

Look for:

• API client documentation
• Authentication/authorization documentation
• JWT generation examples
• Configuration documentation

Files to check:

• README.md
• docs/api.md or docs/auth.md
• src/api/ or src/services/ directories
• Configuration files in src/config/ or root

endorser-ch Repository

Look for:

• API documentation
• Authentication documentation
• README.md (already mentions did-jwt in JWT verification section)
• Route handler documentation

Files to check:

• README.md (check JWT verification section mentioned)
• src/ or server/ directories
• Route files
• Authentication middleware files

---

Quick Decision Guide

After investigation, use this decision matrix:

Finding	Algorithm	Implementation Status
jsonwebtoken + JWT_SECRET	HS256	✅ Already implemented
did-jwt + DID resolution	ES256K	❌ Need to implement
Both found (hybrid)	HS256 for API	✅ Already implemented
Can't determine	Test both	⚠️ Implement both options

---

Next Steps After Investigation

1. If HS256 confirmed:

   • ✅ Mark TODO item #1 as complete
   • ✅ Current implementation is correct
   • ✅ Test against API

2. If DID-based confirmed:

   • ❌ Need to implement DID-based signing
   • Add dependency: did-jwt-java or web3j for Ethereum signing
   • Update generateJWTToken() to use DID private keys
   • Update TODO with findings

3. If hybrid or unclear:

   • Document findings
   • Implement both if needed
   • Add configuration option to switch between methods

---

Investigation Results Template

After investigation, fill out:

## Investigation Results

**Date**: YYYY-MM-DD
**Investigator**: [Name]

### TimeSafari Repository Findings

**createEndorserJwtForDid function:**
- Location: `[file path]`
- Library used: `[jsonwebtoken/did-jwt/etc]`
- Algorithm: `[HS256/ES256K/etc]`
- Key type: `[shared secret/DID private key]`
- Code snippet: `[paste relevant code]`

**Endpoint usage:**
- Location: `[file path]`
- How JWT is generated: `[description]`
- Code snippet: `[paste relevant code]`

### endorser-ch Repository Findings

**Endpoint handler:**
- Location: `[file path]`
- Authentication middleware: `[description]`
- Verification method: `[jsonwebtoken.verify/did-jwt.verifyJWT/etc]`
- Algorithm: `[HS256/ES256K/etc]`
- Secret/key source: `[environment variable/DID resolution/etc]`
- Code snippet: `[paste relevant code]`

### Conclusion

**Algorithm**: [HS256/ES256K/Hybrid/Unclear]
**Action Required**: [Update implementation/Mark complete/etc]

---

Status: Ready for investigation
Priority: CRITICAL - Blocks API authentication