managarten/services/mana-core-auth/README.md

Mana Core Auth

Central authentication and credit management system for the Mana Universe ecosystem.

Features

• JWT-based Authentication (EdDSA/Ed25519 via Better Auth)

  • User registration and login
  • Refresh token rotation
  • Multi-session management
  • Device tracking
  • Automatic key management via JWKS

• Credit System

  • User balance management
  • Transaction ledger with double-entry bookkeeping
  • Optimistic locking for concurrency
  • Daily free credits
  • Signup bonus (150 credits)
  • Idempotency for credit operations

• Security

  • Row-Level Security (RLS) on PostgreSQL
  • Rate limiting
  • CORS protection
  • Helmet security headers
  • SCRAM-SHA-256 password authentication

• Infrastructure

  • Docker-based deployment
  • Traefik reverse proxy with automatic SSL
  • PgBouncer connection pooling
  • Redis caching
  • Prometheus + Grafana monitoring

Quick Start

Development Setup

1. Install dependencies

   pnpm install
   

2. Generate JWT keys

   cd mana-core-auth
   ./scripts/generate-keys.sh
   

3. Set up environment variables

   cp .env.example .env
   # Edit .env and add your JWT keys and other configuration
   

4. Start PostgreSQL and Redis (using Docker)

   docker-compose up postgres redis -d
   

5. Run migrations

   pnpm migration:generate
   pnpm migration:run
   

6. Start development server

   pnpm start:dev
   

   The server will be available at http://localhost:3001/api/v1

Production Deployment (Docker)

1. Set up environment variables

   cp .env.example .env
   # Edit .env with production values
   

2. Generate JWT keys

   ./mana-core-auth/scripts/generate-keys.sh
   # Add the generated keys to .env
   

3. Start all services

   docker-compose up -d
   

4. Check service health

   docker-compose ps
   docker-compose logs -f mana-core-auth
   

API Endpoints

Authentication

POST /api/v1/auth/register

• Register a new user
• Body: { email, password, name? }
• Returns: User object

POST /api/v1/auth/login

• Login with email and password
• Body: { email, password, deviceId?, deviceName? }
• Returns: { user, accessToken, refreshToken, expiresIn, tokenType }

POST /api/v1/auth/refresh

• Refresh access token
• Body: { refreshToken }
• Returns: New token pair

POST /api/v1/auth/logout

• Logout and revoke session
• Requires: Bearer token
• Returns: Success message

POST /api/v1/auth/validate

• Validate a JWT token
• Body: { token }
• Returns: { valid, payload }

Credits

GET /api/v1/credits/balance

• Get current credit balance
• Requires: Bearer token
• Returns: { balance, freeCreditsRemaining, totalEarned, totalSpent }

POST /api/v1/credits/use

• Deduct credits from balance
• Requires: Bearer token
• Body: { amount, appId, description, idempotencyKey?, metadata? }
• Returns: Transaction details

GET /api/v1/credits/transactions?limit=50&offset=0

• Get transaction history
• Requires: Bearer token
• Returns: Array of transactions

GET /api/v1/credits/purchases

• Get purchase history
• Requires: Bearer token
• Returns: Array of purchases

GET /api/v1/credits/packages

• Get available credit packages
• Requires: Bearer token
• Returns: Array of packages

Database Schema

Auth Schema

• auth.users - User accounts
• auth.sessions - Active sessions
• auth.passwords - Hashed passwords
• auth.accounts - OAuth provider accounts
• auth.verification_tokens - Email verification & password reset
• auth.two_factor_auth - 2FA configuration
• auth.security_events - Security audit log

Credits Schema

• credits.balances - User credit balances
• credits.transactions - Transaction ledger
• credits.packages - Available credit packages
• credits.purchases - Purchase history
• credits.usage_stats - Usage analytics

Environment Variables

See .env.example for all available configuration options.

Key variables:

• DATABASE_URL - PostgreSQL connection string
• JWT_ISSUER - JWT issuer claim (default: manacore)
• JWT_AUDIENCE - JWT audience claim (default: manacore)
• REDIS_HOST, REDIS_PORT, REDIS_PASSWORD - Redis configuration
• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET - Stripe integration
• CORS_ORIGINS - Allowed origins for CORS
• CREDITS_SIGNUP_BONUS - Free credits on signup (default: 150)
• CREDITS_DAILY_FREE - Daily free credits (default: 5)

Note: JWT signing keys are managed automatically by Better Auth using EdDSA (Ed25519). Keys are stored in the auth.jwks database table - no manual key configuration needed.

Development

Available Scripts

# Start development server with hot-reload
pnpm start:dev

# Build for production
pnpm build

# Start production server
pnpm start:prod

# Run tests
pnpm test

# Generate database migration
pnpm migration:generate

# Run migrations
pnpm migration:run

# Open Drizzle Studio (database GUI)
pnpm db:studio

# Lint and format
pnpm lint
pnpm format

Architecture

Token Flow

1. User registers/logs in → Receives accessToken (15min) + refreshToken (7 days)
2. Client stores tokens securely (httpOnly cookies on web, SecureStore on mobile)
3. Client includes Authorization: Bearer <accessToken> in requests
4. When access token expires, client uses refresh token to get new pair
5. Refresh tokens are single-use (rotation for security)

Credit System

• Signup Bonus: 150 free credits on registration
• Daily Free Credits: 5 credits added every 24 hours
• Paid Credits: Purchased via Stripe (100 mana = €1)
• Usage Priority: Free credits used first, then paid credits
• Idempotency: Duplicate requests with same key are detected and ignored
• Concurrency: Optimistic locking prevents race conditions

Security Considerations

1. JWT Keys: Managed automatically by Better Auth (EdDSA/Ed25519) - keys stored in auth.jwks table
2. Database: Use strong passwords and enable SSL in production
3. Redis: Always set a password for Redis
4. CORS: Only allow trusted origins
5. Rate Limiting: Configured via Traefik and NestJS throttler
6. RLS Policies: Enforce data isolation at database level
7. HTTPS: Always use SSL/TLS in production (via Traefik)
8. Security Headers: OWASP-compliant headers (HSTS, CSP, X-Frame-Options)
9. Security Audit Logging: Login events tracked in auth.security_events table

Monitoring

• Prometheus: Available at http://localhost:9090
• Grafana: Available at http://localhost:3000
• Logs: docker-compose logs -f mana-core-auth

License

Private - Mana Universe

Support

For issues and questions, contact the development team.