goose 203c0b4331 Research: JWT authentication selected

- Comprehensive JWT research completed
- JWT with refresh tokens selected (9.5/10 score)
- Token revocation strategies (blacklist + versioning)
- Refresh token pattern (token rotation)
- Zero-knowledge password recovery integration
- Family member access control (permissions in JWT)

Key decisions:
- Access tokens: 15 minutes (short-lived)
- Refresh tokens: 30 days (long-lived, stored in MongoDB)
- Token rotation: Prevents reuse of stolen tokens
- Token versioning: Invalidate all tokens on password change
- Recovery phrases: Zero-knowledge password recovery from encryption.md
- Family permissions: parent, child, elderly roles

Updated tech stack decisions

Next: Database schema design (MongoDB collections)

2026-02-14 12:44:33 -03:00

4.3 KiB

Raw Blame History

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:

Client sends refresh_token
Server verifies refresh_token (not revoked, not expired)
Server generates new access_token
Server generates new refresh_token
Server revokes old refresh_token
Server returns new tokens

Why? Prevents reuse of stolen refresh tokens

Zero-Knowledge Password Recovery

Recovery Phrases (from encryption.md)

Registration:

Client generates recovery phrase (random 32 bytes)
Client encrypts recovery phrase with password
Client sends: email, password hash, encrypted recovery phrase
Server stores: email, password hash, encrypted recovery phrase

Password Recovery:

User requests recovery (enters email)
Server returns: encrypted recovery phrase
Client decrypts with recovery key (user enters manually)
User enters new password
Client re-encrypts recovery phrase with new password
Client sends: new password hash, re-encrypted recovery phrase
Server updates: password hash, encrypted recovery phrase, token_version + 1
All existing tokens invalidated (version mismatch)

Family Member Access Control

Permissions in JWT

// 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

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

4.3 KiB Raw Blame History