mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 22:41:09 +02:00
d36b321d9d
Applied formatting to 1487+ files using pnpm format:write - TypeScript/JavaScript files - Svelte components - Astro pages - JSON configs - Markdown docs 13 files still need manual review (Astro JSX comments)
282 lines
6.3 KiB
Markdown
282 lines
6.3 KiB
Markdown
# Mana Core Auth
|
|
|
|
Central authentication and credit management system for the Mana Universe ecosystem.
|
|
|
|
## Features
|
|
|
|
- **JWT-based Authentication** (RS256 algorithm)
|
|
- User registration and login
|
|
- Refresh token rotation
|
|
- Multi-session management
|
|
- Device tracking
|
|
|
|
- **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**
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
2. **Generate JWT keys**
|
|
|
|
```bash
|
|
cd mana-core-auth
|
|
./scripts/generate-keys.sh
|
|
```
|
|
|
|
3. **Set up environment variables**
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add your JWT keys and other configuration
|
|
```
|
|
|
|
4. **Start PostgreSQL and Redis** (using Docker)
|
|
|
|
```bash
|
|
docker-compose up postgres redis -d
|
|
```
|
|
|
|
5. **Run migrations**
|
|
|
|
```bash
|
|
pnpm migration:generate
|
|
pnpm migration:run
|
|
```
|
|
|
|
6. **Start development server**
|
|
|
|
```bash
|
|
pnpm start:dev
|
|
```
|
|
|
|
The server will be available at `http://localhost:3001/api/v1`
|
|
|
|
### Production Deployment (Docker)
|
|
|
|
1. **Set up environment variables**
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with production values
|
|
```
|
|
|
|
2. **Generate JWT keys**
|
|
|
|
```bash
|
|
./mana-core-auth/scripts/generate-keys.sh
|
|
# Add the generated keys to .env
|
|
```
|
|
|
|
3. **Start all services**
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Check service health**
|
|
```bash
|
|
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_PUBLIC_KEY` - RS256 public key (PEM format)
|
|
- `JWT_PRIVATE_KEY` - RS256 private key (PEM format)
|
|
- `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)
|
|
|
|
## Development
|
|
|
|
### Available Scripts
|
|
|
|
```bash
|
|
# 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**: Generate strong RS256 keys and keep private key secure
|
|
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)
|
|
|
|
## 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.
|