@ofeklabs/horizon-auth 0.4.1 → 1.0.0

package/README.md

@@ -1,17 +1,10 @@
 # @ofeklabs/horizon-auth
 
-Production-ready NestJS authentication module with 2026 security standards. One package, two modes: embedded auth or SSO - configured entirely through ENV variables.
+Production-ready NestJS authentication module with 2026 security standards. Deploy once, use everywhere.
 
-## 🎯 Use Cases
+## Use Cases
 
-### 1. Embedded Auth
-Each application has its own isolated authentication. Perfect for standalone apps.
-
-```
-myapp.com (App + Auth)
-```
-
-### 2. Portfolio SSO (Recommended)
+### 1. Portfolio SSO (Recommended)
 Deploy one auth service, use it across all your projects. Users sign in once and access everything.
 
 ```
@@ -22,7 +15,8 @@ auth.yourdomain.com (Auth Service)
     └── project3.yourdomain.com
 ```
 
-**Same package, different ENV variables!** No code changes needed.
+### 2. Embedded Auth
+Each application has its own isolated authentication.
 
 ## Features
 
@@ -35,128 +29,99 @@ auth.yourdomain.com (Auth Service)
 - 🎯 **Type-Safe**: Full TypeScript support
 - 📦 **Zero Config**: Sensible defaults, fully customizable
 
-### 🆕 Enterprise Features (v0.3.0)
+## Quick Start
 
-- 🔒 **Two-Factor Authentication**: TOTP-based 2FA with QR codes and backup codes
-- 📱 **Device Management**: Track, list, and revoke user devices
-- 🔔 **Push Notifications**: Register and manage push tokens (FCM/APNS)
-- 👤 **Account Management**: Deactivate, reactivate, and delete accounts
-- 🌐 **Social Login**: Google and Facebook OAuth integration
+### Portfolio SSO Setup (Recommended)
 
-## 🚀 Quick Start
+Deploy one auth service, use it across all your projects.
 
-### Installation
+#### 1. Deploy Auth Service (One Time)
 
 ```bash
-npm install @ofeklabs/horizon-auth @prisma/client ioredis passport passport-jwt
-npm install -D prisma
+# Clone and deploy packages/horizon-auth to auth.yourdomain.com
+npm install
+npm run build
+npm run start:prod
 ```
 
-### Generate RSA Keys
-
-```bash
-openssl genrsa -out private.pem 2048
-openssl rsa -in private.pem -pubout -out public.pem
+**Environment Variables**:
+```env
+DATABASE_URL=postgresql://...
+REDIS_HOST=your-redis-host
+JWT_PRIVATE_KEY=<your-private-key>
+JWT_PUBLIC_KEY=<your-public-key>
+COOKIE_DOMAIN=.yourdomain.com
+NODE_ENV=production
 ```
 
----
-
-## Configuration Options
-
-### Option 1: Environment Variables Only (Recommended ⭐)
-
-**Zero code configuration** - just set ENV variables and you're done!
+#### 2. Use in Your Projects
 
-#### Embedded Mode (Standalone App)
+For each project:
 
-```env
-# .env
-AUTH_MODE=full
-DATABASE_URL=postgresql://user:password@localhost:5432/myapp
-REDIS_HOST=localhost
-REDIS_PORT=6379
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
-JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
-
-# Optional: Enable features
-ENABLE_2FA=true
-ENABLE_DEVICE_MGMT=true
-ENABLE_PUSH=true
-ENABLE_ACCOUNT_MGMT=true
-APP_NAME=MyApp
+```bash
+npm install @ofeklabs/horizon-auth
 ```
 
 ```typescript
 // app.module.ts
-import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
-
-@Module({
-  imports: [
-    HorizonAuthModule.forRoot(), // 👈 No config needed! Uses ENV variables
-  ],
+HorizonAuthModule.forRoot({
+  ssoMode: true,
+  authServiceUrl: process.env.AUTH_SERVICE_URL,
+  jwt: {
+    publicKey: process.env.JWT_PUBLIC_KEY,
+  },
+  cookie: {
+    domain: process.env.COOKIE_DOMAIN,
+    secure: process.env.NODE_ENV === 'production',
+  },
 })
-export class AppModule {}
 ```
 
-#### SSO Mode (Multiple Projects, One Auth)
-
-**Auth Service (auth.yourdomain.com):**
 ```env
-AUTH_MODE=full
-DATABASE_URL=postgresql://user:password@host:5432/auth_db
-REDIS_HOST=redis.yourdomain.com
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
-JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
-COOKIE_DOMAIN=.yourdomain.com
-NODE_ENV=production
-ENABLE_2FA=true
-ENABLE_DEVICE_MGMT=true
-APP_NAME=YourCompany
-```
-
-**Your Projects (project1.yourdomain.com, project2.yourdomain.com):**
-```env
-AUTH_MODE=sso
+# .env
 AUTH_SERVICE_URL=https://auth.yourdomain.com
-JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
+JWT_PUBLIC_KEY=<paste-public-key>
 COOKIE_DOMAIN=.yourdomain.com
-NODE_ENV=production
 ```
 
-```typescript
-// app.module.ts (same for all projects)
-import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
+Deploy to:
+- project1.yourdomain.com
+- project2.yourdomain.com
+- project3.yourdomain.com
 
-@Module({
-  imports: [
-    HorizonAuthModule.forRoot(), // 👈 Automatically uses SSO mode from ENV
-  ],
-})
-export class AppModule {}
-```
+Users sign in once, access all projects.
 
-**That's it!** Deploy your auth service once, then use the same package in all your projects with different ENV variables. No code changes needed!
+---
 
-**📚 See [ENV-CONFIGURATION.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/ENV-CONFIGURATION.md) for complete ENV reference.**
+### Embedded Auth Setup (Alternative)
 
-**📖 See [DEPLOYMENT-EXAMPLES.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/DEPLOYMENT-EXAMPLES.md) for real-world deployment scenarios.**
+Each application has its own authentication.
 
----
+### 1. Install
 
-### Option 2: Code Configuration (Advanced)
+```bash
+npm install @ofeklabs/horizon-auth @prisma/client ioredis passport passport-jwt
+npm install -D prisma
+```
 
-If you prefer code-based configuration or need dynamic config:
+### 2. Generate RSA Keys
 
-### Option 2: Code Configuration (Advanced)
+```bash
+# Generate private key
+openssl genrsa -out private.pem 2048
 
-If you prefer code-based configuration or need dynamic config:
+# Generate public key
+openssl rsa -in private.pem -pubout -out public.pem
+```
 
-#### Embedded Mode
+### 3. Configure Module
 
 ```typescript
 // app.module.ts
 import { Module } from '@nestjs/common';
 import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
+import { readFileSync } from 'fs';
+import { join } from 'path';
 
 @Module({
   imports: [
@@ -167,19 +132,12 @@ import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
       redis: {
         host: process.env.REDIS_HOST || 'localhost',
         port: parseInt(process.env.REDIS_PORT) || 6379,
+        password: process.env.REDIS_PASSWORD,
       },
       jwt: {
-        privateKey: process.env.JWT_PRIVATE_KEY,
-        publicKey: process.env.JWT_PUBLIC_KEY,
-      },
-      features: {
-        twoFactor: {
-          enabled: true,
-          issuer: 'YourApp',
-        },
-        deviceManagement: {
-          enabled: true,
-        },
+        // For production: use environment variables
+        privateKey: process.env.JWT_PRIVATE_KEY || readFileSync(join(__dirname, '../certs/private.pem'), 'utf8'),
+        publicKey: process.env.JWT_PUBLIC_KEY || readFileSync(join(__dirname, '../certs/public.pem'), 'utf8'),
       },
     }),
   ],
@@ -187,48 +145,17 @@ import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
 export class AppModule {}
 ```
 
-#### SSO Mode
-
-```typescript
-// app.module.ts
-import { HorizonAuthModule } from '@ofeklabs/horizon-auth';
-
-@Module({
-  imports: [
-    HorizonAuthModule.forRoot({
-      ssoMode: true,
-      authServiceUrl: process.env.AUTH_SERVICE_URL,
-      jwt: {
-        publicKey: process.env.JWT_PUBLIC_KEY,
-      },
-      cookie: {
-        domain: process.env.COOKIE_DOMAIN,
-        secure: process.env.NODE_ENV === 'production',
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-**Note:** ENV variables are still loaded automatically. Code config overrides ENV values.
-
----
-
-## 🗄️ Database Setup
+### 4. Set Up Database
 
 ```bash
-# Start PostgreSQL and Redis (using Docker)
-docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:15
-docker run -d -p 6379:6379 redis:7-alpine
+# Start PostgreSQL and Redis
+docker-compose up -d
 
 # Run Prisma migrations
 npx prisma migrate dev
 ```
 
----
-
-## 🎨 Use in Your Application
+### 5. Use in Controllers
 
 ```typescript
 import { Controller, Get, Post, Body, UseGuards } from '@nestjs/common';
@@ -237,6 +164,8 @@ import {
   CurrentUser,
   JwtAuthGuard,
   Roles,
+  LoginDto,
+  RegisterDto,
 } from '@ofeklabs/horizon-auth';
 
 @Controller()
@@ -265,193 +194,69 @@ export class AppController {
 }
 ```
 
----
-
-## 📡 API Endpoints
+## API Endpoints
 
 The package automatically provides these endpoints:
 
-### Core Authentication
+### Authentication
 
 - `POST /auth/register` - Register new user
 - `POST /auth/login` - Login with email/password
 - `POST /auth/refresh` - Refresh access token
 - `POST /auth/logout` - Logout and revoke tokens
 - `GET /auth/profile` - Get current user profile
+
+### Password Management
+
 - `POST /auth/password-reset/request` - Request password reset
 - `POST /auth/password-reset/complete` - Complete password reset
 - `POST /auth/verify-email` - Verify email address
 
-### Enterprise Features (v0.3.0+)
-
-**Two-Factor Authentication:**
-- `POST /auth/2fa/enable` - Enable 2FA and get QR code
-- `POST /auth/2fa/verify` - Verify 2FA setup
-- `POST /auth/2fa/verify-login` - Complete login with 2FA
-- `POST /auth/2fa/disable` - Disable 2FA
-- `POST /auth/2fa/backup-codes/regenerate` - Regenerate backup codes
-
-**Device Management:**
-- `GET /auth/devices` - List user's active devices
-- `POST /auth/devices/:deviceId/revoke` - Revoke specific device
-
-**Push Notifications:**
-- `POST /auth/push-tokens` - Register push notification token
-- `DELETE /auth/push-tokens/:tokenId` - Revoke push token
-
-**Account Management:**
-- `POST /auth/account/deactivate` - Deactivate account
-- `POST /auth/account/reactivate` - Reactivate account
-- `DELETE /auth/account` - Permanently delete account
-
-**Social Login:**
-- `POST /auth/social/google` - Google OAuth callback
-- `POST /auth/social/facebook` - Facebook OAuth callback
-
 ### Cross-Language Support
 
 - `GET /.well-known/jwks.json` - Public keys for JWT verification
 
----
-
-## 🎯 How SSO Mode Works
-
-When you deploy in SSO mode, here's what happens:
-
-1. **Auth Service (auth.yourdomain.com):**
-   - Runs in `AUTH_MODE=full`
-   - Has database and Redis
-   - Handles login, registration, 2FA, etc.
-   - Issues JWT tokens
-   - Sets cookies for `.yourdomain.com`
-
-2. **Your Projects (project1.yourdomain.com, project2.yourdomain.com):**
-   - Run in `AUTH_MODE=sso`
-   - No database or Redis needed
-   - Only verify JWT tokens using public key
-   - Read cookies from `.yourdomain.com`
-   - Users are automatically authenticated!
-
-3. **User Experience:**
-   - User visits `project1.yourdomain.com`
-   - Not logged in → Your frontend redirects to `auth.yourdomain.com/login`
-   - User logs in at auth service
-   - Cookie set for `.yourdomain.com`
-   - Redirect back to `project1.yourdomain.com`
-   - User is now logged in!
-   - User visits `project2.yourdomain.com` → Already logged in! (same cookie)
-
-**Important:** This package is API-only. You need to build your own login/register UI that calls the auth endpoints.
-
----
-
-## 🔧 Configuration Reference
-
-## 🔧 Configuration Reference
-
-### Complete Configuration Interface
+## Configuration Options
 
 ```typescript
 interface HorizonAuthConfig {
-  // Mode Selection
-  ssoMode?: boolean; // false = full auth service, true = token verification only
-  authServiceUrl?: string; // Required when ssoMode=true
-  
-  // Database (required when ssoMode=false)
-  database?: {
+  // Required
+  database: {
     url: string;
   };
-  
-  // Redis (required when ssoMode=false)
-  redis?: {
+  redis: {
     host: string;
     port: number;
     password?: string;
     db?: number;
   };
-  
-  // JWT (always required)
   jwt: {
-    privateKey?: string; // Required when ssoMode=false
-    publicKey: string; // Always required
+    privateKey: string; // RSA private key (PEM format)
+    publicKey: string; // RSA public key (PEM format)
     accessTokenExpiry?: string; // Default: '15m'
     refreshTokenExpiry?: string; // Default: '7d'
     issuer?: string; // Default: 'horizon-auth'
     audience?: string; // Default: 'horizon-api'
-    kid?: string; // Default: 'horizon-auth-key-1'
-  };
-  
-  // Cookie Configuration
-  cookie?: {
-    domain?: string; // e.g., '.yourdomain.com' for SSO
-    secure?: boolean; // Default: true in production
-    sameSite?: 'strict' | 'lax' | 'none'; // Default: 'lax'
   };
-  
-  // Multi-Tenant Support
+
+  // Optional
   multiTenant?: {
     enabled: boolean;
     tenantIdExtractor?: 'header' | 'subdomain' | 'custom';
     defaultTenantId?: string;
   };
-  
-  // Rate Limiting
   rateLimit?: {
     login?: { limit: number; ttl: number };
     register?: { limit: number; ttl: number };
     passwordReset?: { limit: number; ttl: number };
   };
-  
-  // Email Configuration
-  email?: {
-    provider: 'resend' | 'sendgrid' | 'custom';
-    apiKey?: string;
-    from?: string;
-  };
-  
-  // Global Guards
   guards?: {
     applyJwtGuardGlobally?: boolean;
   };
-  
-  // Enterprise Features
-  features?: {
-    twoFactor?: {
-      enabled: boolean;
-      issuer?: string; // Shows in authenticator apps
-    };
-    deviceManagement?: {
-      enabled: boolean;
-      maxDevicesPerUser?: number;
-    };
-    pushNotifications?: {
-      enabled: boolean;
-    };
-    accountManagement?: {
-      enabled: boolean;
-      allowReactivation?: boolean;
-    };
-    socialLogin?: {
-      google?: {
-        clientId: string;
-        clientSecret: string;
-        callbackUrl: string;
-      };
-      facebook?: {
-        appId: string;
-        appSecret: string;
-        callbackUrl: string;
-      };
-    };
-  };
 }
 ```
 
-**💡 Tip:** Use ENV variables instead of code config for maximum flexibility!
-
----
-
-## 🎭 Decorators
+## Decorators
 
 ### @Public()
 Mark routes as publicly accessible (skip authentication)
@@ -495,113 +300,105 @@ getTenantData(@CurrentTenant() tenantId: string) {
 }
 ```
 
-## Enterprise Features Usage
-
-### Two-Factor Authentication
+## Multi-Tenant Configuration
 
 ```typescript
-// Enable 2FA for a user
-const setup = await fetch('/auth/2fa/enable', {
-  method: 'POST',
-  headers: { Authorization: `Bearer ${accessToken}` },
-});
-const { secret, qrCode } = await setup.json();
-
-// Display QR code to user (qrCode is a data URL)
-// User scans with Google Authenticator or Authy
-
-// Verify setup with code from authenticator
-await fetch('/auth/2fa/verify', {
-  method: 'POST',
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-    'Content-Type': 'application/json',
+HorizonAuthModule.forRoot({
+  // ... other config
+  multiTenant: {
+    enabled: true,
+    tenantIdExtractor: 'header', // or 'subdomain' or 'custom'
+    defaultTenantId: 'default',
   },
-  body: JSON.stringify({ code: '123456' }),
 });
+```
 
-// Login with 2FA
-const loginResponse = await fetch('/auth/login', {
-  method: 'POST',
-  body: JSON.stringify({ email, password }),
-});
+## Dev SSO Mode
 
-if (loginResponse.requiresTwoFactor) {
-  // Prompt user for 2FA code
-  await fetch('/auth/2fa/verify-login', {
-    method: 'POST',
-    body: JSON.stringify({
-      userId: loginResponse.userId,
-      code: '123456', // or backup code
-    }),
-  });
-}
+For local development with multiple microservices:
+
+```yaml
+# docker-compose.dev-sso.yml
+version: '3.8'
+services:
+  auth-service:
+    build: .
+    ports:
+      - '3000:3000'
+    environment:
+      COOKIE_DOMAIN: '.localhost'
+      REDIS_HOST: redis
+    depends_on:
+      - postgres
+      - redis
 ```
 
-### Device Management
+All `*.localhost:3000` apps will share the same authentication session.
 
-```typescript
-// List user's devices (automatically tracked on login)
-const devices = await fetch('/auth/devices', {
-  headers: { Authorization: `Bearer ${accessToken}` },
-}).then(r => r.json());
-
-// Revoke a specific device
-await fetch(`/auth/devices/${deviceId}/revoke`, {
-  method: 'POST',
-  headers: { Authorization: `Bearer ${accessToken}` },
-});
-```
+## Cross-Language Token Verification
 
-### Push Notifications
+### C# Example
 
-```typescript
-// Register push token (requires device from login)
-await fetch('/auth/push-tokens', {
-  method: 'POST',
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    token: fcmToken, // From Firebase Cloud Messaging
-    tokenType: 'FCM', // or 'APNS' for iOS
-    deviceId: deviceId, // From device list
-  }),
-});
+```csharp
+using Microsoft.IdentityModel.Tokens;
+using System.IdentityModel.Tokens.Jwt;
+
+var jwks = await httpClient.GetStringAsync("http://auth-service/.well-known/jwks.json");
+var keys = JsonConvert.DeserializeObject<JsonWebKeySet>(jwks);
+
+var tokenHandler = new JwtSecurityTokenHandler();
+var validationParameters = new TokenValidationParameters
+{
+    ValidateIssuerSigningKey = true,
+    IssuerSigningKeys = keys.Keys,
+    ValidateIssuer = true,
+    ValidIssuer = "horizon-auth",
+    ValidateAudience = true,
+    ValidAudience = "horizon-api"
+};
+
+var principal = tokenHandler.ValidateToken(token, validationParameters, out var validatedToken);
 ```
 
-### Account Management
+### Python Example
 
-```typescript
-// Deactivate account
-await fetch('/auth/account/deactivate', {
-  method: 'POST',
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    reason: 'Taking a break',
-  }),
-});
+```python
+import jwt
+import requests
 
-// Reactivate account (no auth required)
-await fetch('/auth/account/reactivate', {
-  method: 'POST',
-  body: JSON.stringify({ email, password }),
-});
+# Fetch JWKS
+jwks_url = "http://auth-service/.well-known/jwks.json"
+jwks = requests.get(jwks_url).json()
 
-// Permanently delete account
-await fetch('/auth/account', {
-  method: 'DELETE',
-  headers: { Authorization: `Bearer ${accessToken}` },
-});
+# Verify token
+token = "your-jwt-token"
+decoded = jwt.decode(
+    token,
+    jwks,
+    algorithms=["RS256"],
+    issuer="horizon-auth",
+    audience="horizon-api"
+)
 ```
 
----
+## Security Best Practices
+
+1. **Always use HTTPS in production**
+2. **Store RSA keys securely** (environment variables, secrets manager)
+3. **Enable rate limiting** to prevent brute force attacks
+4. **Monitor security events** (failed logins, token reuse)
+5. **Rotate JWT keys periodically**
+6. **Use strong Redis passwords** in production
 
-## 🌐 Cross-Language Token Verification
+## Environment Variables
+
+```env
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/horizon_auth
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
 REDIS_PASSWORD=your_redis_password
 
 # JWT Keys (for production - use multiline env vars)
@@ -751,209 +548,22 @@ docker run -p 3000:3000 \
 - All user tokens have been revoked for security
 - User needs to login again
 
-### "Device ID required for push tokens"
-- Push tokens require a valid deviceId
-- Devices are created automatically on login (not registration)
-- Login first, then get device list, then register push token
-
-### "Feature disabled" error
-- The feature you're trying to use is not enabled in configuration
-- Enable it in `HorizonAuthModule.forRoot({ features: { ... } })`
-
-## Testing Status
-
-**✅ Fully Tested:**
-- User registration and login
-- JWT token generation and validation
-- Refresh token rotation
-- 2FA setup (QR code generation)
-- Account deactivation/reactivation
-- Login protection for deactivated accounts
-
-**⚠️ Requires Manual Testing:**
-- 2FA login flow (requires actual authenticator app)
-- Device tracking (automatic on login)
-- Push token registration (requires valid device)
-- Social login (requires OAuth credentials from Google/Facebook)
-- Backup codes usage during login
-
-## 🌐 Cross-Platform Support
-
-**Works with ANY backend language!** Your auth service issues JWT tokens that can be verified by:
-- ✅ NestJS (use package in SSO mode)
-- ✅ .NET / C# (JWT Bearer Auth)
-- ✅ Python (PyJWT)
-- ✅ Go (golang-jwt)
-- ✅ Java / Spring Boot (OAuth2 Resource Server)
-- ✅ PHP (Firebase JWT)
-- ✅ Any language with JWT support!
-
-**📖 See [CROSS-PLATFORM-INTEGRATION.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/CROSS-PLATFORM-INTEGRATION.md) for complete integration guides with code examples.**
-
----
-
-## 🌐 Cross-Language Token Verification
-
-Your other services (in any language) can verify tokens using the JWKS endpoint:
-
-### C# Example
-
-```csharp
-using Microsoft.IdentityModel.Tokens;
-using System.IdentityModel.Tokens.Jwt;
-
-var jwks = await httpClient.GetStringAsync("https://auth.yourdomain.com/.well-known/jwks.json");
-var keys = JsonConvert.DeserializeObject<JsonWebKeySet>(jwks);
-
-var tokenHandler = new JwtSecurityTokenHandler();
-var validationParameters = new TokenValidationParameters
-{
-    ValidateIssuerSigningKey = true,
-    IssuerSigningKeys = keys.Keys,
-    ValidateIssuer = true,
-    ValidIssuer = "horizon-auth",
-    ValidateAudience = true,
-    ValidAudience = "horizon-api"
-};
-
-var principal = tokenHandler.ValidateToken(token, validationParameters, out var validatedToken);
-```
-
-### Python Example
-
-```python
-import jwt
-import requests
-
-# Fetch JWKS
-jwks_url = "https://auth.yourdomain.com/.well-known/jwks.json"
-jwks = requests.get(jwks_url).json()
-
-# Verify token
-token = "your-jwt-token"
-decoded = jwt.decode(
-    token,
-    jwks,
-    algorithms=["RS256"],
-    issuer="horizon-auth",
-    audience="horizon-api"
-)
-```
-
----
-
-## 🐛 Troubleshooting
-
-### "AUTH_SERVICE_URL is required when AUTH_MODE=sso"
-Set `AUTH_SERVICE_URL` in your ENV file when using SSO mode.
-
-### "JWT_PRIVATE_KEY is required when AUTH_MODE=full"
-Make sure you've set `JWT_PRIVATE_KEY` when running in full mode (auth service).
-
-### "Invalid or expired access token"
-- Check that your JWT keys are correctly configured
-- Verify token hasn't expired (default 15 minutes)
-- Ensure token isn't blacklisted in Redis
-
-### "Redis connection error"
-- Verify Redis is running: `docker ps` or check your cloud Redis service
-- Check Redis connection settings in ENV
-- Test connection: `redis-cli ping`
-
-### "Token reuse detected"
-- This is a security feature - someone tried to reuse a revoked refresh token
-- All user tokens have been revoked for security
-- User needs to login again
-
-### "Device ID required for push tokens"
-- Push tokens require a valid deviceId
-- Devices are created automatically on login (not registration)
-- Login first, then get device list, then register push token
+## Migration from Existing Auth
 
-### "Feature disabled" error
-- The feature you're trying to use is not enabled
-- Enable it via ENV: `ENABLE_2FA=true`, `ENABLE_DEVICE_MGMT=true`, etc.
+See [MIGRATION.md](./MIGRATION.md) for guides on:
+- Migrating from bcrypt to Argon2id
+- Migrating from HS256 to RS256
+- Database schema migration
 
-### Cookies not working across subdomains
-- Make sure `COOKIE_DOMAIN` starts with a dot: `.yourdomain.com`
-- Verify `COOKIE_SECURE=true` in production (requires HTTPS)
-- Check that all apps use the same cookie domain
-
----
-
-## 📚 Documentation
-
-- **[ENV-CONFIGURATION.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/ENV-CONFIGURATION.md)** - Complete environment variable reference
-- **[DEPLOYMENT-EXAMPLES.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/DEPLOYMENT-EXAMPLES.md)** - Real-world deployment scenarios
-- **[CROSS-PLATFORM-INTEGRATION.md](https://github.com/OfekItzhaki/horizon-auth-platform/blob/main/CROSS-PLATFORM-INTEGRATION.md)** - Integration with .NET, Python, Go, Java, PHP
-- **[GitHub Repository](https://github.com/OfekItzhaki/horizon-auth-platform)** - Source code and issues
-
----
-
-## 🧪 Testing Status
-
-**✅ Fully Tested:**
-- User registration and login
-- JWT token generation and validation
-- Refresh token rotation
-- 2FA setup (QR code generation)
-- Account deactivation/reactivation
-- Login protection for deactivated accounts
-- SSO mode token verification
-
-**⚠️ Requires Manual Testing:**
-- 2FA login flow (requires actual authenticator app)
-- Device tracking (automatic on login)
-- Push token registration (requires valid device)
-- Social login (requires OAuth credentials from Google/Facebook)
-- Backup codes usage during login
-
----
-
-## 📦 What's New
-
-### v0.4.1 (Latest)
-- 📝 **Cross-platform integration guide** - Complete examples for .NET, Python, Go, Java, PHP
-- 📝 Enhanced README with cross-platform support section
-- 🌐 JWKS endpoint documentation for polyglot architectures
-
-### v0.4.0
-- ✨ **ENV-based configuration** - Zero code changes needed!
-- ✨ **Flexible deployment** - Same package for embedded and SSO modes
-- 📝 Complete ENV variable documentation
-- 📝 Real-world deployment examples
-- 🔧 Improved configuration merging
-
-### v0.3.0
-- ✨ Two-Factor Authentication (TOTP)
-- ✨ Device Management
-- ✨ Push Notifications
-- ✨ Account Management
-- ✨ Social Login (Google, Facebook)
-
-### v0.2.1
-- 🐛 Fixed SSO mode JWT strategy
-- 🔧 Dynamic module configuration
-
----
-
-## 📄 License
+## License
 
 MIT
 
----
-
-## 🤝 Support
-
-- **Issues:** [GitHub Issues](https://github.com/OfekItzhaki/horizon-auth-platform/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/OfekItzhaki/horizon-auth-platform/discussions)
+## Support
 
----
-
-## 👨‍💻 Author
+- GitHub Issues: https://github.com/OfekItzhaki/horizon-auth-platform/issues
+- Documentation: https://github.com/OfekItzhaki/horizon-auth-platform
 
-Created by **Ofek Itzhaki**
-
----
+## Credits
 
-**⭐ If this package helps you, consider giving it a star on GitHub!**
+Created by Ofek Itzhaki