normogen/docs/adr/jwt-authentication-decision.md

# JWT Authentication Decision Summary

**Date**: 2026-02-14
**Decision**: **JWT with Refresh Tokens + Recovery Phrases**

---

## Authentication Strategy

### Primary: JWT (JSON Web Tokens)

**Why JWT?**
- Stateless design scales to 1000+ concurrent connections
- Works perfectly with mobile apps (AsyncStorage)
- No server-side session storage needed
- Easy to scale Axum horizontally

### Token Types

**Access Token** (15 minutes)
- Used for API requests
- Short-lived for security
- Contains: user_id, email, family_id, permissions

**Refresh Token** (30 days)
- Used to get new access tokens
- Long-lived for convenience
- Stored in MongoDB for revocation
- Rotated on every refresh

---

## Token Revocation Strategies

### 1. Refresh Token Blacklist (Recommended) ⭐
- Store refresh tokens in MongoDB
- Mark as revoked on logout
- Check on every refresh

### 2. Token Versioning
- Include version in JWT claims
- Increment on password change
- Invalidate all tokens when version changes

### 3. Access Token Blacklist (Optional)
- Store revoked access tokens in Redis
- For immediate revocation
- Auto-expires with TTL

---

## Refresh Token Pattern

### Token Rotation (Security Best Practice) ⭐

**Flow**:
1. Client sends refresh_token
2. Server verifies refresh_token (not revoked, not expired)
3. Server generates new access_token
4. Server generates new refresh_token
5. Server revokes old refresh_token
6. Server returns new tokens

**Why?** Prevents reuse of stolen refresh tokens

---

## Zero-Knowledge Password Recovery

### Recovery Phrases (from encryption.md)

**Registration**:
1. Client generates recovery phrase (random 32 bytes)
2. Client encrypts recovery phrase with password
3. Client sends: email, password hash, encrypted recovery phrase
4. Server stores: email, password hash, encrypted recovery phrase

**Password Recovery**:
1. User requests recovery (enters email)
2. Server returns: encrypted recovery phrase
3. Client decrypts with recovery key (user enters manually)
4. User enters new password
5. Client re-encrypts recovery phrase with new password
6. Client sends: new password hash, re-encrypted recovery phrase
7. Server updates: password hash, encrypted recovery phrase, token_version + 1
8. All existing tokens invalidated (version mismatch)

---

## Family Member Access Control

### Permissions in JWT

```typescript
// JWT permissions based on family role
{
  "parent": [
    "read:own_data",
    "write:own_data",
    "read:family_data",
    "write:family_data",
    "manage:family_members",
    "delete:data"
  ],
  "child": [
    "read:own_data",
    "write:own_data"
  ],
  "elderly": [
    "read:own_data",
    "write:own_data",
    "read:family_data"
  ]
}
```

### Permission Middleware

- Check permissions on protected routes
- Return 403 Forbidden if insufficient permissions
- Works with JWT claims

---

## Technology Stack

### Backend (Axum)
- jsonwebtoken 9.x (JWT crate)
- bcrypt 0.15 (password hashing)
- mongodb 3.0 (refresh token storage)
- redis (optional, for access token blacklist)

### Client (React Native + React)
- AsyncStorage (token storage)
- axios (API client with JWT interceptor)
- PBKDF2 (password derivation)
- AES-256-GCM (data encryption)

---

## Implementation Timeline

- **Week 1**: Basic JWT (login, register, middleware)
- **Week 1-2**: Refresh tokens (storage, rotation)
- **Week 2**: Token revocation (blacklist, versioning)
- **Week 2-3**: Password recovery (recovery phrases)
- **Week 3**: Family access control (permissions)
- **Week 3-4**: Security hardening (rate limiting, HTTPS)

**Total**: 3-4 weeks

---

## Next Steps

1. Implement basic JWT service in Axum
2. Create MongoDB schema for users and refresh tokens
3. Implement login/register/refresh/logout handlers
4. Create JWT middleware for protected routes
5. Implement token revocation (blacklist + versioning)
6. Integrate password recovery (from encryption.md)
7. Implement family access control (permissions)
8. Test entire authentication flow
9. Create client-side authentication (React Native + React)

---

## References

- [Comprehensive JWT Research](./2026-02-14-jwt-authentication-research.md)
- [Normogen Encryption Guide](../encryption.md)
- [JWT RFC 7519](https://tools.ietf.org/html/rfc7519)
- [Axum JWT Guide](https://docs.rs/axum/latest/axum/)
- [OWASP JWT Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html)