# 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

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

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

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

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

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

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

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

```markdown
## 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