Authentication

MealPal uses Better-Auth for self-hosted authentication, replacing an earlier Clerk integration.

Why Better-Auth?

• Self-hosted — full control over user data, no vendor lock-in
• EdDSA (Ed25519) — modern, fast JWT signing algorithm
• JWKS — standard key rotation and verification
• 2FA support — TOTP-based two-factor authentication

How It Works

1. Better-Auth runs as a sidecar Node.js service in Docker Compose
2. It manages its own auth database on RDS (separate from the main mealpal database)
3. JWTs are signed with Ed25519 and verified by the FastAPI backend using JWKS
4. The frontend uses Better-Auth’s React SDK for login/signup flows

Key Files

File	Purpose
backend/app/core/auth.py	JWT verification, JWKS fetching, demo mode bypass
auth/src/index.ts	Better-Auth server configuration
frontend/src/lib/auth-client.ts	Frontend auth client setup

Demo Mode

For unauthenticated access, demo mode uses header-based auth bypass:

• X-Demo-Mode: true — enables demo mode
• X-Demo-User-Id: demo-user — sets a fixed demo user ID

This is checked in backend/app/core/auth.py before JWT verification.