permissions-contractx 1.0.0

package/README.md

@@ -0,0 +1,1397 @@
+# 🔐 Permissions ContractX
+
+A comprehensive **NestJS authentication and authorization package** designed for microservices in the ContractX ecosystem. This package provides JWT-based authentication, role-based access control (RBAC), and granular permission management.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![NestJS](https://img.shields.io/badge/NestJS-E0234E?style=flat&logo=nestjs&logoColor=white)](https://nestjs.com/)
+[![JWT](https://img.shields.io/badge/JWT-000000?style=flat&logo=JSON%20web%20tokens)](https://jwt.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🔑 **JWT Authentication** - Secure token-based authentication
+- 👥 **Role-Based Access Control** - Hierarchical role system
+- 🔐 **Permission-Based Authorization** - Granular permission control
+- 🏢 **Multi-Tenant Support** - Client/Provider organizational structure
+- 🚀 **Easy Integration** - Simple decorator-based API
+- 🛡️ **Security First** - Built-in security best practices
+- 📊 **Request Context** - User context service for easy access
+- 🔧 **TypeScript** - Full TypeScript support with strict typing
+- 📖 **Comprehensive Documentation** - Detailed examples and guides
+
+## 📦 Installation
+
+```bash
+npm install permissions-contractx
+```
+
+### Peer Dependencies
+
+Make sure you have the required peer dependencies installed:
+
+```bash
+npm install @nestjs/common @nestjs/core @nestjs/jwt @nestjs/config jsonwebtoken rxjs reflect-metadata
+```
+
+## 🚀 Quick Start
+
+### 1. Basic Setup
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { PermissionsContractXModule } from 'permissions-contractx';
+
+@Module({
+  imports: [
+    PermissionsContractXModule.register({
+      jwt: {
+        secret: 'your-secret-key',
+        issuer: 'your-api',
+        audience: 'your-users',
+        expiresIn: '15m',
+      },
+      guards: {
+        enableGlobalAuth: true, // Apply authentication globally
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Using Decorators in Controllers
+
+```typescript
+import { Controller, Get, Post, UseGuards } from '@nestjs/common';
+import {
+  CurrentUser,
+  Roles,
+  RequirePermissions,
+  Public,
+  JwtAuthGuard,
+  RolesGuard,
+  PermissionsGuard,
+  JwtPayload,
+} from 'permissions-contractx';
+
+@Controller('users')
+@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
+export class UsersController {
+  
+  // Public endpoint (no authentication)
+  @Public()
+  @Get('public')
+  getPublicInfo() {
+    return { message: 'This is public' };
+  }
+
+  // Authenticated endpoint
+  @Get('profile')
+  getProfile(@CurrentUser() user: JwtPayload) {
+    return {
+      id: user.sub,
+      name: user.fullName,
+      roles: user.role,
+      permissions: user.permissions,
+    };
+  }
+
+  // Role-based access
+  @Roles('superadmin', 'client_contract_admin')
+  @Get('admin-data')
+  getAdminData() {
+    return { message: 'Admin only data' };
+  }
+
+  // Permission-based access
+  @RequirePermissions('users.create')
+  @Post()
+  createUser(@CurrentUser() user: JwtPayload) {
+    return { message: 'User created', createdBy: user.fullName };
+  }
+
+  // Combined role and permission
+  @Roles('client_contract_admin')
+  @RequirePermissions('users.delete')
+  @Delete(':id')
+  deleteUser(@Param('id') id: string) {
+    return { message: `User ${id} deleted` };
+  }
+}
+```
+
+### 3. Environment Variables Setup
+
+Create a `.env` file:
+
+```env
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+JWT_ISSUER=contractx-api
+JWT_AUDIENCE=contractx-users
+JWT_EXPIRES_IN=15m
+
+# Optional: Enable global guards
+ENABLE_GLOBAL_AUTH=true
+ENABLE_AUTH_LOGGING=true
+
+# Development only
+DISABLE_AUTH=false  # Set to true to disable auth in development
+```
+
+### 4. Auto-Configuration with Environment Variables
+
+```typescript
+// app.module.ts - Easiest setup
+@Module({
+  imports: [
+    PermissionsContractXModule.forRoot(), // Auto-configures from environment variables
+  ],
+})
+export class AppModule {}
+```
+
+## 🏗️ Advanced Configuration
+
+### Async Configuration
+
+```typescript
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    PermissionsContractXModule.registerAsync({
+      imports: [ConfigModule],
+      useFactory: async (configService: ConfigService) => ({
+        jwt: {
+          secret: configService.get('JWT_SECRET'),
+          issuer: configService.get('JWT_ISSUER'),
+          audience: configService.get('JWT_AUDIENCE'),
+          expiresIn: configService.get('JWT_EXPIRES_IN', '15m'),
+          clockTolerance: 30, // seconds
+        },
+        guards: {
+          enableGlobalAuth: true,
+          enableGlobalRoles: false,
+          enableGlobalPermissions: false,
+        },
+        security: {
+          enableLogging: process.env.NODE_ENV === 'production',
+        },
+        development: {
+          disableAuth: process.env.NODE_ENV === 'development',
+          mockUser: {
+            sub: 'dev-user-123',
+            role: ['superadmin'],
+            permissions: ['*'],
+            fullName: 'Development User',
+            email: 'dev@example.com',
+          },
+        },
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## 📋 JWT Token Structure
+
+The JWT token must include the following payload structure:
+
+```json
+{
+  "sub": "user_123456789",      // User ID (required)
+  "fullName": "John Doe",       // User's full name (required)
+  "email": "john@example.com",  // User's email
+  "clientId": "client_001",     // Organization/Client ID
+  "sessionId": "session_abc",   // Session tracking
+  
+  "role": [                     // User roles array (required)
+    "admin",
+    "manager",
+    "user"
+  ],
+  
+  "permissions": [              // User permissions array (required)
+    "users:read",
+    "users:create",
+    "users:update",
+    "users:delete",
+    "settings:manage"
+  ],
+  
+  // Standard JWT fields
+  "iat": 1609459200,           // Issued at
+  "exp": 1609545600,           // Expires at
+  "iss": "contractx-api",      // Issuer
+  "aud": "contractx-users"     // Audience
+}
+```
+
+## 🛡️ Guards
+
+### 1. JwtAuthGuard
+
+Validates JWT tokens and extracts user information.
+
+```typescript
+import { Controller, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard } from 'permissions-contractx';
+
+@Controller('protected')
+@UseGuards(JwtAuthGuard)
+export class ProtectedController {
+  // All routes require valid JWT token
+}
+```
+
+### 2. RolesGuard
+
+Checks if user has required roles.
+
+```typescript
+import { Controller, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard, RolesGuard, RequireRoles } from 'permissions-contractx';
+
+@Controller('admin')
+@UseGuards(JwtAuthGuard, RolesGuard)
+export class AdminController {
+  
+  @Get('dashboard')
+  @RequireRoles('admin', 'manager') // User must have admin OR manager role
+  getDashboard() {
+    return { message: 'Admin dashboard' };
+  }
+}
+```
+
+### 3. PermissionsGuard
+
+Checks if user has required permissions.
+
+```typescript
+import { Controller, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard, PermissionsGuard, RequirePermissions } from 'permissions-contractx';
+
+@Controller('users')
+@UseGuards(JwtAuthGuard, PermissionsGuard)
+export class UsersController {
+  
+  @Post()
+  @RequirePermissions('users:create') // User must have this exact permission
+  createUser() {
+    return { message: 'User created' };
+  }
+
+  @Delete(':id')
+  @RequirePermissions('users:delete', 'admin:all') // User must have one of these
+  deleteUser() {
+    return { message: 'User deleted' };
+  }
+}
+```
+
+## 🎯 Decorators
+
+The permissions-contractx package provides a comprehensive set of decorators for authentication and authorization in your NestJS applications.
+
+### 🔐 Authentication Decorators
+
+#### `@Public()`
+Marks routes as public (no authentication required). Essential for login endpoints, health checks, and public APIs.
+
+```typescript
+@Controller('auth')
+export class AuthController {
+  @Public()
+  @Post('login')
+  login(@Body() credentials: LoginDto) {
+    return this.authService.login(credentials);
+  }
+  
+  @Public()
+  @Get('health')
+  getHealth() {
+    return { status: 'OK', timestamp: new Date() };
+  }
+}
+```
+
+#### `@CurrentUser(property?)`
+Injects the current authenticated user or specific user properties into route handlers.
+
+```typescript
+@Controller('users')
+export class UsersController {
+  // Inject full user object
+  @Get('profile')
+  getProfile(@CurrentUser() user: JwtPayload) {
+    return {
+      id: user.sub,
+      name: user.fullName,
+      email: user.email,
+      roles: user.role,
+      permissions: user.permissions
+    };
+  }
+  
+  // Inject specific user property
+  @Post('actions')
+  performAction(
+    @CurrentUser('sub') userId: string,
+    @CurrentUser('fullName') userName: string,
+    @Body() actionData: any
+  ) {
+    return {
+      action: 'completed',
+      performedBy: userName,
+      userId: userId,
+      data: actionData
+    };
+  }
+}
+```
+
+#### `@UserId()`
+Convenience decorator to get the current user's ID directly.
+
+```typescript
+@Controller('resources')
+export class ResourcesController {
+  @Post()
+  createResource(
+    @UserId() userId: string,
+    @Body() resourceData: CreateResourceDto
+  ) {
+    return this.resourcesService.create({
+      ...resourceData,
+      createdBy: userId,
+      createdAt: new Date()
+    });
+  }
+  
+  @Get('my-resources')
+  getMyResources(@UserId() userId: string) {
+    return this.resourcesService.findByUser(userId);
+  }
+}
+```
+
+#### `@UserRoles()`
+Injects the current user's roles array into the route handler.
+
+```typescript
+@Controller('dashboard')
+export class DashboardController {
+  @Get('capabilities')
+  getUserCapabilities(@UserRoles() roles: string[]) {
+    const capabilities = {
+      canManageUsers: roles.includes('superadmin') || roles.includes('client_contract_admin'),
+      canViewReports: roles.some(role => role.includes('reports')),
+      canManageContracts: roles.some(role => role.includes('contract_admin')),
+      isClientSide: roles.some(role => role.startsWith('client_')),
+      isProviderSide: roles.some(role => role.startsWith('provider_'))
+    };
+    
+    return { roles, capabilities };
+  }
+}
+```
+
+#### `@UserPermissions()`
+Injects the current user's permissions array into the route handler.
+
+```typescript
+@Controller('admin')
+export class AdminController {
+  @Get('available-actions')
+  getAvailableActions(@UserPermissions() permissions: string[]) {
+    const modulePermissions = permissions.reduce((acc, permission) => {
+      const [module, action] = permission.split(':');
+      if (!acc[module]) acc[module] = [];
+      acc[module].push(action);
+      return acc;
+    }, {});
+    
+    return {
+      totalPermissions: permissions.length,
+      moduleBreakdown: modulePermissions,
+      rawPermissions: permissions
+    };
+  }
+}
+```
+
+#### `@UserClientId()`
+Injects the current user's client ID for multi-tenant applications.
+
+```typescript
+@Controller('tenant')
+export class TenantController {
+  @Get('data')
+  getTenantData(@UserClientId() clientId: string) {
+    return this.dataService.findByClient(clientId);
+  }
+  
+  @Post('settings')
+  updateTenantSettings(
+    @UserClientId() clientId: string,
+    @Body() settings: TenantSettingsDto
+  ) {
+    return this.settingsService.update(clientId, settings);
+  }
+}
+```
+
+### 👥 Role-Based Authorization Decorators
+
+#### `@Roles(...roles)`
+Requires user to have **at least one** of the specified roles (OR logic).
+
+```typescript
+@Controller('admin')
+export class AdminController {
+  // User needs superadmin OR any contract admin role
+  @Roles('superadmin', 'client_contract_admin', 'provider_contract_admin')
+  @Get('dashboard')
+  getAdminDashboard() {
+    return { message: 'Admin dashboard data' };
+  }
+  
+  // Multiple specific roles
+  @Roles('client_finance_manager', 'provider_finance_manager')
+  @Get('financial-reports')
+  getFinancialReports() {
+    return this.reportsService.getFinancialData();
+  }
+}
+```
+
+#### `@AdminOnly()`
+Shortcut for admin-level access (superadmin, client_contract_admin, provider_contract_admin).
+
+```typescript
+@Controller('system')
+export class SystemController {
+  @AdminOnly()
+  @Delete('cache')
+  clearCache() {
+    return this.cacheService.clear();
+  }
+  
+  @AdminOnly()
+  @Post('maintenance-mode')
+  enableMaintenanceMode(@Body() config: MaintenanceConfigDto) {
+    return this.systemService.enableMaintenance(config);
+  }
+}
+```
+
+#### `@ClientOnly()`
+Restricts access to client-side roles only.
+
+```typescript
+@Controller('client')
+export class ClientController {
+  @ClientOnly()
+  @Get('performance-metrics')
+  getClientPerformanceMetrics(@UserClientId() clientId: string) {
+    return this.metricsService.getClientMetrics(clientId);
+  }
+  
+  @ClientOnly()
+  @Post('escalation')
+  createEscalation(@Body() escalationData: CreateEscalationDto) {
+    return this.escalationService.create(escalationData);
+  }
+}
+```
+
+#### `@ProviderOnly()`
+Restricts access to provider-side roles only.
+
+```typescript
+@Controller('provider')
+export class ProviderController {
+  @ProviderOnly()
+  @Get('delivery-schedule')
+  getDeliverySchedule() {
+    return this.deliveryService.getSchedule();
+  }
+  
+  @ProviderOnly()
+  @Put('deliverable/:id/status')
+  updateDeliverableStatus(
+    @Param('id') id: string,
+    @Body() statusUpdate: DeliverableStatusDto
+  ) {
+    return this.deliverableService.updateStatus(id, statusUpdate);
+  }
+}
+```
+
+#### `@SuperAdminOnly()`
+Restricts access to superadmin role only.
+
+```typescript
+@Controller('system-admin')
+export class SystemAdminController {
+  @SuperAdminOnly()
+  @Post('create-tenant')
+  createTenant(@Body() tenantData: CreateTenantDto) {
+    return this.tenantService.create(tenantData);
+  }
+  
+  @SuperAdminOnly()
+  @Delete('user/:id')
+  deleteUser(@Param('id') userId: string) {
+    return this.userService.delete(userId);
+  }
+}
+```
+
+### 🔐 Permission-Based Authorization Decorators
+
+#### `@RequirePermissions(...permissions)`
+Requires user to have **all** specified permissions (AND logic).
+
+```typescript
+@Controller('contracts')
+export class ContractsController {
+  // User must have ALL specified permissions
+  @RequirePermissions('contracts.create', 'contracts.validate')
+  @Post()
+  createContract(@Body() contractData: CreateContractDto) {
+    return this.contractService.create(contractData);
+  }
+  
+  // Single permission requirement
+  @RequirePermissions('contracts.delete')
+  @Delete(':id')
+  deleteContract(@Param('id') id: string) {
+    return this.contractService.delete(id);
+  }
+}
+```
+
+#### `@RequireAnyPermission(...permissions)`
+Requires user to have **at least one** of the specified permissions (OR logic).
+
+```typescript
+@Controller('documents')
+export class DocumentsController {
+  // User needs ANY of these permissions
+  @RequireAnyPermission('documents.read', 'documents.show', 'documents.filter')
+  @Get()
+  getDocuments(@Query() filters: DocumentFiltersDto) {
+    return this.documentService.findAll(filters);
+  }
+  
+  // Administrative permissions
+  @RequireAnyPermission('documents.admin', 'superadmin.all')
+  @Post('batch-process')
+  batchProcessDocuments(@Body() batchData: BatchProcessDto) {
+    return this.documentService.batchProcess(batchData);
+  }
+}
+```
+
+### 🎯 Module-Level Permission Decorators
+
+These decorators provide convenient access patterns based on common CRUD operations:
+
+#### `@ReadAccess(module)`
+Grants read access to a module (read, show, or filter permissions).
+
+```typescript
+@Controller('reports')
+export class ReportsController {
+  @ReadAccess('reports')
+  @Get('financial')
+  getFinancialReports() {
+    // User needs reports.read, reports.show, OR reports.filter
+    return this.reportsService.getFinancialReports();
+  }
+  
+  @ReadAccess('contracts')
+  @Get('contract-summary')
+  getContractSummary() {
+    // User needs contracts.read, contracts.show, OR contracts.filter
+    return this.contractService.getSummary();
+  }
+}
+```
+
+#### `@WriteAccess(module)`
+Grants write access to a module (create or update permissions).
+
+```typescript
+@Controller('users')
+export class UsersController {
+  @WriteAccess('users')
+  @Post()
+  createUser(@Body() userData: CreateUserDto) {
+    // User needs users.create OR users.update
+    return this.userService.create(userData);
+  }
+  
+  @WriteAccess('users')
+  @Put(':id')
+  updateUser(
+    @Param('id') id: string,
+    @Body() userData: UpdateUserDto
+  ) {
+    // User needs users.create OR users.update
+    return this.userService.update(id, userData);
+  }
+}
+```
+
+#### `@DeleteAccess(module)`
+Grants delete access to a module.
+
+```typescript
+@Controller('deliverables')
+export class DeliverablesController {
+  @DeleteAccess('deliverables')
+  @Delete(':id')
+  deleteDeliverable(@Param('id') id: string) {
+    // User needs deliverables.delete
+    return this.deliverableService.delete(id);
+  }
+}
+```
+
+#### `@FullAccess(module)`
+Grants full CRUD access to a module (any module permission).
+
+```typescript
+@Controller('admin/modules')
+export class ModuleAdminController {
+  @FullAccess('users')
+  @Post('users/bulk-operation')
+  bulkUserOperation(@Body() operation: BulkOperationDto) {
+    // User needs ANY users module permission
+    return this.userService.bulkOperation(operation);
+  }
+}
+```
+
+### 🔄 Combining Decorators
+
+Decorators can be combined for complex authorization logic:
+
+```typescript
+@Controller('advanced')
+export class AdvancedController {
+  // Combine role and permission requirements
+  @Roles('client_contract_admin', 'provider_contract_admin')
+  @RequirePermissions('contracts.approve')
+  @Put('contracts/:id/approve')
+  approveContract(
+    @Param('id') contractId: string,
+    @CurrentUser() user: JwtPayload
+  ) {
+    return this.contractService.approve(contractId, user.sub);
+  }
+  
+  // Complex permission logic
+  @ClientOnly()
+  @RequireAnyPermission('reports.generate', 'reports.admin')
+  @Post('custom-report')
+  generateCustomReport(
+    @Body() reportSpec: CustomReportDto,
+    @UserClientId() clientId: string
+  ) {
+    return this.reportsService.generateCustom(reportSpec, clientId);
+  }
+  
+  // Multiple permission sets
+  @RequirePermissions('documents.create')
+  @RequireAnyPermission('contracts.update', 'deliverables.update')
+  @Post('document-with-linking')
+  createLinkedDocument(
+    @Body() documentData: LinkedDocumentDto,
+    @UserId() userId: string
+  ) {
+    // User must have documents.create AND (contracts.update OR deliverables.update)
+    return this.documentService.createWithLinking(documentData, userId);
+  }
+}
+```
+
+### 🏷️ Method vs Class Level Decorators
+
+Decorators can be applied at both class and method levels:
+
+```typescript
+// Class-level decorators apply to all methods
+@Controller('secure')
+@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
+@ClientOnly() // All methods require client roles
+export class SecureController {
+  @Get('data')
+  getData() {
+    // Inherits @ClientOnly from class
+    return this.dataService.getClientData();
+  }
+  
+  @RequirePermissions('admin.override')
+  @Get('admin-data')
+  getAdminData() {
+    // Combines @ClientOnly + @RequirePermissions
+    return this.dataService.getAdminData();
+  }
+  
+  @Public() // Overrides class-level @ClientOnly
+  @Get('public-info')
+  getPublicInfo() {
+    return { message: 'Public information' };
+  }
+}
+```
+
+## 🛠️ Services
+
+### UserContextService
+
+Access user information and check permissions programmatically:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { UserContextService } from 'permissions-contractx';
+
+@Injectable()
+export class MyService {
+  constructor(private userContext: UserContextService) {}
+
+  async doSomething() {
+    // Get user information
+    const user = this.userContext.getUser();
+    const userId = this.userContext.getUserId();
+    const roles = this.userContext.getUserRoles();
+
+    // Check permissions
+    if (this.userContext.hasRole('admin')) {
+      // Do admin stuff
+    }
+
+    if (this.userContext.hasPermission('users.create')) {
+      // Can create users
+    }
+
+    if (this.userContext.isClientUser()) {
+      // Client-side user logic
+    }
+
+    // Get user summary for logging
+    const summary = this.userContext.getUserSummary();
+    console.log('User accessing service:', summary);
+  }
+}
+```
+
+## 🚫 Error Handling
+
+The package provides specific error messages for different authentication and authorization failures:
+
+### Common Error Responses
+
+```json
+// 401 - Missing token
+{
+  "statusCode": 401,
+  "message": "Access token is required",
+  "error": "Unauthorized"
+}
+
+// 401 - Invalid token
+{
+  "statusCode": 401,
+  "message": "Invalid access token",
+  "error": "Unauthorized"
+}
+
+// 401 - Expired token
+{
+  "statusCode": 401,
+  "message": "Access token has expired",
+  "error": "Unauthorized"
+}
+
+// 403 - Insufficient permissions
+{
+  "statusCode": 403,
+  "message": "Insufficient permissions. Required: users:create",
+  "error": "Forbidden"
+}
+
+// 403 - Missing roles
+{
+  "statusCode": 403,
+  "message": "Insufficient roles. Required: admin",
+  "error": "Forbidden"
+}
+```
+
+### Custom Error Handling
+
+```typescript
+import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
+import { UnauthorizedException, ForbiddenException } from '@nestjs/common';
+
+@Catch(UnauthorizedException, ForbiddenException)
+export class AuthExceptionFilter implements ExceptionFilter {
+  catch(exception: UnauthorizedException | ForbiddenException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    
+    // Custom error handling logic
+    response.status(exception.getStatus()).json({
+      statusCode: exception.getStatus(),
+      message: exception.message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+## 💾 Database Integration & ODS Seeder
+
+### ODS Roles and Permissions Seeder
+
+The package includes a complete seeder for the ODS (Operational Data Store) roles and permissions matrix with **16 predefined roles** and **23 modules**:
+
+```typescript
+import { ContractXRolePermissionSeeder } from '@your-org/permissions-contractx';
+
+@Injectable()
+export class DatabaseSeederService {
+  constructor(
+    private readonly seeder: ContractXRolePermissionSeeder,
+    // Your repository dependencies
+    @InjectRepository(Role) private roleRepo: Repository<Role>,
+    @InjectRepository(Permission) private permissionRepo: Repository<Permission>,
+    @InjectRepository(RolePermission) private rolePermissionRepo: Repository<RolePermission>
+  ) {}
+
+  async seedRolesAndPermissions() {
+    const { roles, permissions, rolePermissions } = await this.seeder.seed();
+    
+    // Save to database
+    const savedRoles = await this.roleRepo.save(roles);
+    const savedPermissions = await this.permissionRepo.save(permissions);
+    
+    // Update IDs for role-permission mappings
+    const mappingsWithIds = rolePermissions.map(rp => ({
+      ...rp,
+      roleId: savedRoles.find(r => r.name === roles.find(role => role.id === rp.roleId)?.name)?.id,
+      permissionId: savedPermissions.find(p => p.name === permissions.find(perm => perm.id === rp.permissionId)?.name)?.id
+    }));
+    
+    await this.rolePermissionRepo.save(mappingsWithIds);
+    
+    // Validate seeded data
+    const isValid = await this.seeder.validateSeed(savedRoles, savedPermissions, mappingsWithIds);
+    if (!isValid) {
+      throw new Error('Seeder validation failed');
+    }
+    
+    // Get statistics
+    const stats = this.seeder.getSeederStats();
+    console.log('Seeding completed:', stats);
+    /*
+    Output:
+    {
+      totalRoles: 16,
+      totalPermissions: 161, // 23 modules × 7 actions each
+      totalModules: 23,
+      rolesByType: {
+        system: 4,
+        client: 6,
+        provider: 6
+      },
+      permissionsByCategory: {
+        contract_management: 98,
+        financial: 21,
+        system_admin: 21,
+        user_management: 7,
+        client_management: 7,
+        provider_management: 7
+      }
+    }
+    */
+  }
+}
+```
+
+### ODS Roles Matrix (16 Roles)
+
+The seeder creates the following roles based on the complete ODS specification:
+
+#### 🔧 System Roles
+- **superadmin**: Full system access to all modules
+- **support**: Broad access excluding client management
+- **auditor**: Read-only audit and compliance access
+- **guest**: Limited read-only access
+
+#### 👥 Client-Side Roles
+- **client_contract_admin**: Full contract management for client
+- **client_performance_manager**: SLA and performance management
+- **client_finance_manager**: Financial operations and invoicing
+- **client_reports_manager**: Reporting and analytics
+- **client_relationship_manager**: Relationship and meeting management
+- **client_risk_manager**: Risk and security management
+
+#### 🏢 Provider-Side Roles
+- **provider_contract_admin**: Provider contract administration
+- **provider_performance_manager**: Provider performance management
+- **provider_finance_manager**: Provider financial operations
+- **provider_relationship_manager**: Provider relationship management
+- **provider_risk_manager**: Provider risk management
+- **provider_operator**: Operational support and deliverable management
+
+### 📊 ODS Modules (23 Modules)
+
+The seeder covers all ContractX modules with comprehensive CRUD permissions:
+
+- **Core Management**: clients, contracts, users, providers, documents, clauses
+- **Deliverables**: deliverables, subdeliverables, deliverable_history
+- **SLA Management**: sla_services, measurement_windows, credit_service_levels
+- **Collaboration**: meetings, meeting_participants, action_items
+- **Notifications**: notification_escalations
+- **Financial**: invoice_services, invoice_lines
+- **System**: security_control, configuration, workflows
+
+### Database Entity Examples
+
+For database integration with TypeORM, implement the seeder interfaces:
+
+```typescript
+// Role Entity
+@Entity('roles')
+export class Role implements RoleEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ unique: true })
+  name: string;
+
+  @Column()
+  displayName: string;
+
+  @Column()
+  description: string;
+
+  @Column()
+  type: string;
+
+  @Column()
+  scope: string;
+
+  @Column()
+  level: number;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @Column()
+  tenantAssociation: string;
+
+  @Column('jsonb')
+  metadata: Record<string, any>;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+
+// Permission Entity
+@Entity('permissions')
+export class Permission implements PermissionEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ unique: true })
+  name: string;
+
+  @Column()
+  displayName: string;
+
+  @Column()
+  description: string;
+
+  @Column()
+  module: string;
+
+  @Column()
+  action: string;
+
+  @Column()
+  category: string;
+
+  @Column()
+  scope: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @Column('jsonb')
+  metadata: Record<string, any>;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+
+// Role-Permission Junction
+@Entity('role_permissions')
+export class RolePermission implements RolePermissionEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  roleId: string;
+
+  @Column()
+  permissionId: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @Column('jsonb', { nullable: true })
+  metadata: Record<string, any>;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+
+// User entity example with JWT payload
+@Entity('users')
+export class User implements JwtPayload {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  email: string;
+
+  @Column('simple-array')
+  roles: string[];
+
+  @Column('simple-array')
+  permissions: string[];
+
+  @Column({ nullable: true })
+  clientId?: string;
+
+  @Column({ nullable: true })
+  providerId?: string;
+
+  @Column()
+  firstName: string;
+
+  @Column()
+  lastName: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+```
+
+### Integration with Auth Service
+
+```typescript
+// In your auth-service-contract
+@Injectable()
+export class AuthService {
+  constructor(
+    private readonly seeder: ContractXRolePermissionSeeder,
+    private readonly authorizationService: ContractXAuthorizationService,
+    private readonly validationService: ContractXValidationService,
+  ) {}
+
+  async initializeSystem() {
+    // Seed ODS roles and permissions
+    await this.seeder.seed();
+  }
+
+  async validateUserAccess(user: JwtPayload, requiredPermission: string) {
+    return this.authorizationService.checkPermission(user, requiredPermission);
+  }
+
+  async getUserAccessMatrix(user: JwtPayload) {
+    return this.authorizationService.generateAccessMatrix(user);
+  }
+}
+```
+
+## 🌍 Environment Variables
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `JWT_SECRET` | JWT signing secret | - | ✅ Yes |
+| `JWT_ISSUER` | Token issuer | `contractx-api` | No |
+| `JWT_AUDIENCE` | Token audience | `contractx-users` | No |
+| `JWT_EXPIRES_IN` | Token expiration | `15m` | No |
+| `JWT_CLOCK_TOLERANCE` | Clock tolerance (seconds) | `0` | No |
+| `ENABLE_GLOBAL_AUTH` | Apply auth guard globally | `false` | No |
+| `ENABLE_GLOBAL_ROLES` | Apply roles guard globally | `false` | No |
+| `ENABLE_GLOBAL_PERMISSIONS` | Apply permissions guard globally | `false` | No |
+| `ENABLE_AUTH_LOGGING` | Enable security logging | `false` | No |
+| `DISABLE_AUTH` | Disable authentication | `false` | No |
+
+## 🔒 Security Best Practices
+
+### 1. JWT Token Structure
+
+The package expects JWT tokens with this payload structure:
+
+```typescript
+interface JwtPayload {
+  sub: string;                // User ID
+  role: string[];            // User roles
+  permissions: string[];     // User permissions
+  fullName: string;          // User's full name
+  email?: string;            // User's email
+  clientId?: string;         // Organization/client ID
+  sessionId?: string;        // Session tracking
+  iat?: number;             // Issued at
+  exp?: number;             // Expires at
+}
+```
+
+### 2. Environment Variables
+
+```env
+# Required
+JWT_SECRET=your-256-bit-secret-key-here
+JWT_ISSUER=your-api-name
+JWT_AUDIENCE=your-api-users
+
+# Optional but recommended
+JWT_EXPIRES_IN=15m
+JWT_CLOCK_TOLERANCE=30
+
+# Security
+ENABLE_AUTH_LOGGING=true
+```
+
+### 3. Global Guards
+
+```typescript
+// For maximum security, enable global authentication
+PermissionsContractXModule.register({
+  guards: {
+    enableGlobalAuth: true,    // All routes require auth by default
+    enableGlobalRoles: false,  // Only specific routes check roles
+    enableGlobalPermissions: false, // Only specific routes check permissions
+  },
+})
+```
+
+## 🧪 Testing
+
+### Unit Testing
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { JwtService } from '@nestjs/jwt';
+import { JwtAuthGuard } from 'permissions-contractx';
+
+describe('Authentication', () => {
+  let guard: JwtAuthGuard;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        JwtAuthGuard,
+        {
+          provide: JwtService,
+          useValue: { verifyAsync: jest.fn() },
+        },
+        // ... other providers
+      ],
+    }).compile();
+
+    guard = module.get(JwtAuthGuard);
+  });
+
+  it('should authenticate valid token', async () => {
+    // Test implementation
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+import * as request from 'supertest';
+
+describe('Protected Routes', () => {
+  it('should reject unauthenticated requests', () => {
+    return request(app.getHttpServer())
+      .get('/protected-route')
+      .expect(401);
+  });
+
+  it('should allow authenticated requests', () => {
+    return request(app.getHttpServer())
+      .get('/protected-route')
+      .set('Authorization', `Bearer ${validToken}`)
+      .expect(200);
+  });
+});
+```
+
+## 🚀 Production Deployment
+
+### Docker Support
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+
+ENV NODE_ENV=production
+ENV JWT_SECRET=${JWT_SECRET}
+ENV JWT_ISSUER=contractx-production
+
+EXPOSE 3000
+CMD ["npm", "run", "start:prod"]
+```
+
+### Environment Configuration
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  app:
+    build: .
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=${JWT_SECRET}
+      - JWT_ISSUER=contractx-api
+      - JWT_AUDIENCE=contractx-users
+      - ENABLE_AUTH_LOGGING=true
+```
+
+## 📖 Examples
+
+### Complete Controller Example
+
+```typescript
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Body,
+  Param,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  JwtAuthGuard,
+  RolesGuard,
+  PermissionsGuard,
+  CurrentUser,
+  Roles,
+  RequirePermissions,
+  Public,
+  ClientOnly,
+  AdminOnly,
+  JwtPayload,
+} from 'permissions-contractx';
+
+@Controller('contracts')
+@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
+export class ContractsController {
+  
+  @Public()
+  @Get('health')
+  getHealth() {
+    return { status: 'OK' };
+  }
+
+  @Get()
+  @RequirePermissions('contracts.read', 'contracts.filter')
+  async getContracts(@CurrentUser() user: JwtPayload) {
+    // User must have both read AND filter permissions
+    return { contracts: [], requestedBy: user.fullName };
+  }
+
+  @Post()
+  @ClientOnly()
+  @RequirePermissions('contracts.create')
+  async createContract(
+    @Body() contractData: any,
+    @CurrentUser() user: JwtPayload,
+  ) {
+    // Only client-side users with create permission
+    return { id: '123', createdBy: user.sub };
+  }
+
+  @Put(':id/approve')
+  @AdminOnly()
+  @RequirePermissions('contracts.approve')
+  async approveContract(
+    @Param('id') id: string,
+    @CurrentUser() user: JwtPayload,
+  ) {
+    // Only admins with approval permission
+    return { id, approvedBy: user.fullName, approvedAt: new Date() };
+  }
+
+  @Delete(':id')
+  @Roles('superadmin')
+  async deleteContract(@Param('id') id: string) {
+    // Only superadmin can delete
+    return { message: `Contract ${id} deleted` };
+  }
+}
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📧 Email: support@contractx.dev
+- 🐛 Issues: [GitHub Issues](https://github.com/your-org/permissions-contractx/issues)
+- 📚 Documentation: [Full Documentation](https://permissions-contractx.dev)
+
+## 📊 Package Stats
+
+- ✅ **Zero Dependencies** (only peer dependencies)
+- 🚀 **TypeScript First** - Built with TypeScript for TypeScript
+- 📦 **Tree Shakeable** - Only import what you need
+- 🔒 **Security Focused** - Built with security best practices
+- 🧪 **Well Tested** - Comprehensive test coverage
+
+---
+
+Made with ❤️ by the ContractX Team