exguard-backend 1.0.39 → 1.1.0

package/README.md

@@ -1,1271 +1,183 @@
-# ExGuard Backend SDK v2.0
+# ExGuard Backend SDK
 
-🛡️ **Enterprise-grade RBAC protection for NestJS applications** with intelligent caching and realtime support.
+Simple RBAC/ABAC permission guard for NestJS.
 
-A powerful backend SDK specifically optimized for NestJS, providing seamless role-based access control with decorators, guards, and 95%+ performance improvement through smart caching.
-
-## 🚀 Why ExGuard for NestJS?
-
-- **🎯 NestJS-Native Design** - Built specifically for NestJS with decorators and guards
-- **⚡ 95% Performance Boost** - Smart caching eliminates redundant API calls
-- **🔄 Realtime Updates** - Automatic cache invalidation on RBAC changes
-- **🛡️ Comprehensive Protection** - Permissions, roles, modules, and field offices
-- **📊 Performance Monitoring** - Built-in cache statistics and optimization
-- **🔧 Zero Configuration** - Works out of the box with sensible defaults
-
-## 📦 Installation
-
-```bash
-npm install exguard-backend
-# or
-yarn add exguard-backend
-# or
-pnpm add exguard-backend
-```
-
-## 🚀 Quick Start - NestJS Integration
-
-### 🎯 Option 1: Automatic Setup (Recommended)
-
-**One-command setup for NestJS projects:**
+## Installation
 
 ```bash
-# Install exguard-backend
 npm install exguard-backend
-
-# Run automatic setup (overwrites existing files)
-npx exguard-backend
-# OR
-npm run setup-nestjs
-```
-
-**Quick Start - NestJS Integration:**
-
-After running the setup script, you can quickly start using ExGuard:
-
-```bash
-# Start development server
-npm run start:dev
-
-# The setup script automatically:
-# ✅ Creates src/exguard/ directory with all guards and decorators
-# ✅ Updates src/app.module.ts with ExGuardModule import
-# ✅ Creates src/events/events.controller.ts with working examples
-# ✅ Adds npm scripts for easy access
 ```
-✅ **Improved module detection** - More reliable NestJS project detection  
-✅ **Enhanced file creation** - Better file path handling  
-✅ **TypeScript error fixes** - All generated code is type-safe  
-✅ **Complete imports** - All factory functions properly imported  
-✅ **Working permission checks** - Guards actually enforce permissions
-
-### 📋 Option 2: Manual Setup
 
-If you prefer manual setup, follow these steps:
+## Quick Setup
 
-#### Step 1: Install Dependencies
-
-```bash
-npm install exguard-backend @nestjs/core @nestjs/common @nestjs/platform-express
-```
+### 1. Copy Guard Files
 
-#### Step 2: Create ExGuard Module
+Create `src/exguard/exguard.guard.ts`:
 
 ```typescript
-// src/exguard/exguard.module.ts
-import { Module, Global } from '@nestjs/common';
-import { Guard } from 'exguard-backend';
-
-@Global()
-@Module({
-  providers: [
-    {
-      provide: Guard,
-      useFactory: () => new Guard({
-        apiUrl: process.env.EXGUARD_API_URL || 'http://localhost:3000',
-        cache: { enabled: true, ttl: 300000 }, // 5 minutes cache
-      }),
-    },
-  ],
-  exports: [Guard],
-})
-export class ExGuardModule {}
-```
-
-#### Step 3: Create Custom Guards
+import { Injectable, CanActivate, ExecutionContext, UnauthorizedException, ForbiddenException, Inject, Optional } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ExGuardBackend } from 'exguard-backend';
 
-```typescript
-// src/exguard/exguard.guard.ts
-import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
-import { Guard, GuardContext } from 'exguard-backend';
+export const EXGUARD_PERMISSIONS_KEY = 'exguard_permissions';
+export const EXGUARD_ROLES_KEY = 'exguard_roles';
 
 @Injectable()
-export class ExGuardNestGuard implements CanActivate {
-  constructor(protected exGuard: Guard) {}
+export class ExGuardPermissionGuard implements CanActivate {
+  constructor(
+    @Optional() @Inject('EXGUARD_INSTANCE') private exGuard: ExGuardBackend,
+    private reflector: Reflector,
+  ) {}
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest();
     const token = this.extractToken(request);
-    
-    const guardContext: GuardContext = { token, request };
-    const result = await this.exGuard.authenticate(guardContext);
-    
-    if (!result.allowed) {
-      throw new ForbiddenException(result.error);
-    }
-
-    request.user = result.user;
-    return true;
-  }
-
-  protected extractToken(request: any): string | null {
-    const authHeader = request.headers?.authorization;
-    return authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
-  }
-}
-
-// Permission-specific guard
-@Injectable()
-export class ExGuardPermissionGuard extends ExGuardNestGuard {
-  protected async checkPermissions(context: GuardContext) {
-    return this.exGuard.requirePermissions(context, ['read']);
-  }
-}
-
-// Factory functions for dynamic guards
-export function createPermissionGuard(permissions: string[], requireAll = false) {
-  return class extends ExGuardNestGuard {
-    protected async checkPermissions(context: GuardContext) {
-      return this.exGuard.requirePermissions(context, permissions, { requireAll });
-    }
-  };
-}
-```
-
-#### Step 4: Protect Your Controllers
-
-```typescript
-// src/events/events.controller.ts
-import { Controller, Get, Post, Body, UseGuards, Request } from '@nestjs/common';
-import { createPermissionGuard } from '../exguard/exguard.guard';
-
-@Controller('events')
-@UseGuards(ExGuardPermissionGuard) // Requires 'read' permission
-export class EventsController {
-  @Get()
-  async getEvents(@Request() req) {
-    console.log('User:', req.user);
-    return { success: true, data: [] };
-  }
-
-  @Post()
-  @UseGuards(createPermissionGuard(['events:create']))
-  async createEvent(@Body() createEventDto: any, @Request() req) {
-    return { success: true, data: createEventDto };
-  }
-
-  @Put(':id')
-  @UseGuards(createPermissionGuard(['events:update', 'events:admin']))
-  async updateEvent(@Param('id') id: string, @Body() updateDto: any) {
-    return { success: true, data: { id, ...updateDto } };
-  }
-}
-```
-
-#### Step 5: Update App Module
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ExGuardModule } from './exguard/exguard.module';
-import { EventsController } from './events/events.controller';
-
-@Module({
-  imports: [ExGuardModule],
-  controllers: [EventsController],
-})
-export class AppModule {}
-```
-
-### 🎯 Automatic Setup Features
-
-The automatic setup creates a complete NestJS integration:
-
-#### **Generated Files:**
-```
-src/
-├── exguard/
-│   ├── exguard.module.ts      # Global ExGuard module
-│   ├── exguard.guard.ts       # Custom guards
-│   ├── exguard.decorators.ts  # Permission decorators
-│   └── guards/              # Additional guard files
-├── events/
-│   └── events.controller.ts  # Example controller
-└── .env                    # Environment configuration
-```
-
-#### **Generated Decorators:**
-```typescript
-@RequirePermissions(['events:read'])
-@RequireRoles(['Admin'])
-@RequireModules(['reporting'])
-@RequireFieldOffices(['FO-MANILA'])
-```
-
-#### **Generated Package Scripts:**
-```json
-{
-  "scripts": {
-    "exguard:setup": "node node_modules/exguard-backend/scripts/setup-nestjs.js",
-    "exguard:example": "node node_modules/exguard-backend/scripts/create-example.js"
-  }
-}
-```
-
-## 🎯 Advanced NestJS Examples
-
-### Role-Based Protection
-
-```typescript
-// src/admin/admin.controller.ts
-import { Controller, Get, UseGuards } from '@nestjs/common';
-import { createRoleGuard } from '../exguard/exguard.guard';
-
-@Controller('admin')
-@UseGuards(createRoleGuard(['Admin'])) // Requires 'Admin' role
-export class AdminController {
-  @Get('users')
-  async getUsers() {
-    return { success: true, data: [] };
-  }
-
-  @Get('stats')
-  @UseGuards(createRoleGuard(['Admin', 'SuperAdmin'])) // Admin OR SuperAdmin
-  async getStats() {
-    return { success: true, data: { totalUsers: 100 } };
-  }
-}
-```
-
-### Module-Based Protection
-
-```typescript
-// src/reports/reports.controller.ts
-import { Controller, Get, UseGuards } from '@nestjs/common';
-import { createModuleGuard } from '../exguard/exguard.guard';
-
-@Controller('reports')
-@UseGuards(createModuleGuard(['reporting'])) // Requires access to 'reporting' module
-export class ReportsController {
-  @Get()
-  async getReports() {
-    return { success: true, data: [] };
-  }
-
-  @Get('analytics')
-  @UseGuards(createModuleGuard(['analytics', 'reporting'])) // analytics OR reporting
-  async getAnalytics() {
-    return { success: true, data: { pageViews: 10000 } };
-  }
-}
-```
-
-### Complex Multi-Requirement Protection
-
-```typescript
-// src/sensitive/sensitive.controller.ts
-import { Controller, Post, Body, UseGuards } from '@nestjs/common';
-import { Guard } from 'exguard-backend';
-import { ExGuardNestGuard } from '../exguard/exguard.guard';
-
-@Controller('sensitive')
-export class SensitiveController {
-  constructor(private exGuard: Guard) {}
 
-  @Post('execute')
-  @UseGuards(new (class extends ExGuardNestGuard {
-    protected async checkPermissions(context: any) {
-      return this.exGuard.require(context, {
-        permissions: ['sensitive:execute'],
-        roles: ['Manager'],
-        modules: ['operations'],
-        requireAll: true // Must satisfy ALL conditions
-      });
-    }
-  })(this.exGuard))
-  async executeSensitiveOperation(@Body() operation: any) {
-    return { success: true, operation };
-  }
-}
-```
+    if (!token) throw new UnauthorizedException('No token provided');
+    if (!this.exGuard) return true;
 
-### Dynamic Permission Checking
+    const authResult = await this.exGuard.authenticate({ token, request });
 
-```typescript
-// src/dynamic/dynamic.controller.ts
-import { Controller, Get, Param, UseGuards, HttpException, HttpStatus } from '@nestjs/common';
-import { Guard } from 'exguard-backend';
-import { ExGuardNestGuard } from '../exguard/exguard.guard';
-
-@Controller('dynamic')
-@UseGuards(ExGuardNestGuard) // Only authentication, no specific permission
-export class DynamicController {
-  constructor(private exGuard: Guard) {}
+    if (!authResult.allowed) throw new ForbiddenException(authResult.error || 'Access denied');
+    if (!authResult.user) throw new ForbiddenException('User not found');
 
-  @Get('resource/:resourceType/:resourceId')
-  async getResource(@Param('resourceType') resourceType: string, @Request() req) {
-    // Dynamic permission based on resource type
-    const permission = `${resourceType}:read`;
-    
-    const result = await this.exGuard.requirePermissions(
-      { token: this.extractToken(req) },
-      [permission]
-    );
+    const handler = context.getHandler();
+    const permMeta = this.reflector.get(EXGUARD_PERMISSIONS_KEY, handler);
 
-    if (!result.allowed) {
-      throw new HttpException(`Access denied to ${resourceType}`, HttpStatus.FORBIDDEN);
-    }
+    if (permMeta) {
+      const { permissions, requireAll } = permMeta;
+      const userPermissions = authResult.user.modules?.flatMap(m => m.permissions) || [];
 
-    return { success: true, data: { resourceType, content: '...' } };
-  }
-
-  private extractToken(req: any): string {
-    const authHeader = req.headers?.authorization;
-    return authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : '';
-  }
-}
-```
-
-## 🔧 Environment Configuration
-
-### Development Environment
-
-```env
-# .env.development
-EXGUARD_API_URL=http://localhost:3000
-EXGUARD_CACHE_ENABLED=true
-EXGUARD_CACHE_TTL=60000
-EXGUARD_REALTIME_ENABLED=false
-```
-
-### Production Environment
-
-```env
-# .env.production
-EXGUARD_API_URL=https://api.your-domain.com
-EXGUARD_CACHE_ENABLED=true
-EXGUARD_CACHE_TTL=300000
-# Optional: Enable realtime for automatic cache invalidation
-# EXGUARD_REALTIME_ENABLED=true
-# EXGUARD_REALTIME_URL=wss://api.your-domain.com/realtime
-# EXGUARD_SERVICE_TOKEN=your-service-token
-```
-
-### ⚠️ Troubleshooting
-
-**502 WebSocket Error:**
-- This means the realtime server is not running or the URL is incorrect
-- **Solution:** Set `EXGUARD_REALTIME_ENABLED=false` in your .env file
-- The SDK will work without realtime (cache invalidation will be manual)
-
-```env
-EXGUARD_REALTIME_ENABLED=false
-```
-
-**To enable realtime later:**
-1. Make sure your WebSocket server is running
-2. Set correct URL: `EXGUARD_REALTIME_URL=ws://your-server:3000/realtime`
-3. Enable: `EXGUARD_REALTIME_ENABLED=true`
-
-## 📊 Performance Benefits
-
-| Operation | Without Cache | With Cache | Improvement |
-|-----------|---------------|------------|-------------|
-| Single Permission Check | ~100ms | ~5ms | **95% faster** |
-| 10 Permission Checks | ~1000ms | ~10ms | **99% faster** |
-| 100 Concurrent Requests | ~10s | ~0.5s | **95% faster** |
-
-## 🧪 Testing NestJS Integration
-
-### Unit Test Example
-
-```typescript
-// test/exguard.guard.spec.ts
-import { Test, TestingModule } from '@nestjs/testing';
-import { Guard } from 'exguard-backend';
-import { ExGuardNestGuard } from '../src/exguard/exguard.guard';
-
-describe('ExGuardNestGuard', () => {
-  let guard: ExGuardNestGuard;
-  let exGuard: jest.Mocked<Guard>;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [
-        ExGuardNestGuard,
-        {
-          provide: Guard,
-          useValue: {
-            authenticate: jest.fn(),
-            requirePermissions: jest.fn(),
-            requireRoles: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    guard = module.get<ExGuardNestGuard>(ExGuardNestGuard);
-    exGuard = module.get(Guard);
-  });
-
-  it('should allow access with valid token', async () => {
-    const mockContext = {
-      switchToHttp: () => ({
-        getRequest: () => ({
-          headers: { authorization: 'Bearer valid-token' },
-        }),
-      }),
-    };
-
-    exGuard.authenticate.mockResolvedValue({
-      allowed: true,
-      user: { id: '1', roles: ['User'] },
-    });
-
-    const result = await guard.canActivate(mockContext as any);
-    expect(result).toBe(true);
-  });
-});
-```
-
-### Integration Test Example
-
-```typescript
-// test/app.e2e-spec.ts
-import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication } from '@nestjs/common';
-import * as request from 'supertest';
-import { AppModule } from '../src/app.module';
-
-describe('AppController (e2e)', () => {
-  let app: INestApplication;
-
-  beforeEach(async () => {
-    const moduleFixture: TestingModule = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    await app.init();
-  });
-
-  it('should protect endpoints', () => {
-    return request(app.getHttpServer())
-      .get('/events')
-      .expect(401); // No token provided
-  });
-
-  it('should allow access with valid token', () => {
-    return request(app.getHttpServer())
-      .get('/events')
-      .set('Authorization', 'Bearer valid-token')
-      .expect(200);
-  });
-});
-```
-
-## 🚀 Quick Implementation Guide
-
-### **Step 1: Install and Setup**
-```bash
-# Install latest version
-npm install exguard-backend
-
-# Run automatic setup (overwrites existing files)
-npx exguard-backend
-```
-
-### **Step 2: Controller Implementation**
-```typescript
-import { Controller, Get, Post, UseGuards, Request, Body } from '@nestjs/common';
-import { createPermissionGuard, createRoleGuard, createModuleGuard } from '../exguard/exguard.guard';
-
-@Controller('your-controller')
-export class YourController {
-  @Get()
-  @UseGuards(createPermissionGuard(['your-resource:read']))
-  async getAll(@Request() req) {
-    return { success: true, data: [] };
-  }
-
-  @Post()
-  @UseGuards(createPermissionGuard(['your-resource:create']))
-  async create(@Body() createDto: any, @Request() req) {
-    return { success: true, data: createDto };
-  }
-}
-```
-
-### **Step 3: Test Your Implementation**
-```bash
-# Test with valid permissions
-curl http://localhost:3000/your-controller -H "Authorization: Bearer YOUR_TOKEN"
-
-# Test with invalid permissions (should return 403)
-curl http://localhost:3000/your-controller -H "Authorization: Bearer TOKEN_WITHOUT_PERMISSIONS"
-```
-
-### **Important Notes:**
-- ✅ **File Overwriting**: The setup script now overwrites existing files to ensure you get the latest fixes
-- ✅ **Permission Checking**: Guards now actually check and enforce permissions
-- ✅ **TypeScript Safe**: All generated code is TypeScript compliant
-- ✅ **Working Examples**: The generated controller demonstrates all protection patterns
-
-## 🎯 Controller Implementation Examples
-
-### **Basic Permission Protection**
-
-#### **Simple Permission Guard**
-```typescript
-import { Controller, Get, Post, UseGuards, Request, Body } from '@nestjs/common';
-import { createPermissionGuard } from '../exguard/exguard.guard';
-
-@Controller('events')
-export class EventsController {
-  @Get()
-  @UseGuards(createPermissionGuard(['events:read']))
-  async getEvents(@Request() req) {
-    console.log('User accessing events:', req.user);
-    return { success: true, data: [] };
-  }
-
-  @Post()
-  @UseGuards(createPermissionGuard(['events:create']))
-  async createEvent(@Body() createEventDto: any, @Request() req) {
-    console.log('User creating event:', req.user);
-    return { success: true, data: createEventDto };
-  }
-}
-```
-
-#### **Multiple Permissions (Require All)**
-```typescript
-@Get('admin')
-@UseGuards(createPermissionGuard(['admin:access', 'events:manage'], true))
-async getAdminEvents(@Request() req) {
-  return { success: true, data: [], message: 'Admin events' };
-}
-```
-
-#### **Multiple Permissions (Require Any)**
-```typescript
-@Get('reports')
-@UseGuards(createPermissionGuard(['reports:view', 'events:read'], false))
-async getReports(@Request() req) {
-  return { success: true, data: [], message: 'Reports data' };
-}
-```
-
-### **Role-Based Protection**
-
-#### **Role Guards**
-```typescript
-import { createRoleGuard } from '../exguard/exguard.guard';
-
-@Controller('admin')
-export class AdminController {
-  @Get()
-  @UseGuards(createRoleGuard(['Admin']))
-  async getAdminData(@Request() req) {
-    return { success: true, data: [], message: 'Admin data' };
-  }
-
-  @Get('super')
-  @UseGuards(createRoleGuard(['SuperAdmin', 'Admin'], false))
-  async getSuperData(@Request() req) {
-    return { success: true, data: [], message: 'Super admin data' };
-  }
-}
-```
-
-### **Module-Based Protection**
-
-#### **Module Guards**
-```typescript
-import { createModuleGuard } from '../exguard/exguard.guard';
-
-@Controller('reporting')
-export class ReportingController {
-  @Get()
-  @UseGuards(createModuleGuard(['reporting']))
-  async getReports(@Request() req) {
-    return { success: true, data: [], message: 'Reports data' };
-  }
-
-  @Get('finance')
-  @UseGuards(createModuleGuard(['finance', 'reporting'], true))
-  async getFinanceReports(@Request() req) {
-    return { success: true, data: [], message: 'Finance reports' };
-  }
-}
-```
-
-### **Decorator-Based Protection**
-
-#### **Using Decorators with Base Guard**
-```typescript
-import { 
-  RequirePermissions, 
-  RequireRoles, 
-  RequireModules 
-} from '../exguard/exguard.decorators';
-import { ExGuardPermissionGuard } from '../exguard/exguard.guard';
-
-@Controller('users')
-@UseGuards(ExGuardPermissionGuard) // Base guard for authentication
-export class UsersController {
-  @Get()
-  @RequirePermissions(['users:read'])
-  async getUsers(@Request() req) {
-    return { success: true, data: [] };
-  }
-
-  @Post()
-  @RequirePermissions(['users:create'])
-  async createUser(@Body() createUserDto: any, @Request() req) {
-    return { success: true, data: createUserDto };
-  }
-
-  @Get('admin')
-  @RequireRoles(['Admin'])
-  async getAdminUsers(@Request() req) {
-    return { success: true, data: [], message: 'Admin users' };
-  }
-
-  @Get('management')
-  @RequireModules(['user-management'])
-  async getManagementData(@Request() req) {
-    return { success: true, data: [], message: 'Management data' };
-  }
-}
-```
-
-### **Complex Combined Protection**
-
-#### **Using Combined Decorators**
-```typescript
-import { Require } from '../exguard/exguard.decorators';
-
-@Controller('critical')
-@UseGuards(ExGuardPermissionGuard)
-export class CriticalController {
-  @Get('data')
-  @Require({
-    permissions: ['critical:access'],
-    roles: ['Admin'],
-    modules: ['security'],
-    requireAll: true // Must have ALL of the above
-  })
-  async getCriticalData(@Request() req) {
-    return { success: true, data: [], message: 'Critical data' };
-  }
-
-  @Get('flexible')
-  @Require({
-    permissions: ['basic:access'],
-    roles: ['User', 'Manager'],
-    requireAll: false // Can have ANY of the above
-  })
-  async getFlexibleData(@Request() req) {
-    return { success: true, data: [], message: 'Flexible data' };
-  }
-}
-```
-
-#### **Alternative: Separate Decorators (Recommended for clarity)**
-```typescript
-@Controller('alternative')
-@UseGuards(ExGuardPermissionGuard)
-export class AlternativeController {
-  @Get('data')
-  @RequirePermissions(['critical:access'])
-  @RequireRoles(['Admin'])
-  @RequireModules(['security'])
-  async getCriticalData(@Request() req) {
-    return { success: true, data: [], message: 'Critical data' };
-  }
-
-  @Get('flexible')
-  @RequirePermissions(['basic:access'])
-  @RequireRoles(['User', 'Manager'], false) // Any role
-  async getFlexibleData(@Request() req) {
-    return { success: true, data: [], message: 'Flexible data' };
-  }
-}
-```
-
-### **Custom Guard Implementation**
-
-#### **Extending Base Guard**
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ExGuardNestGuard } from '../exguard/exguard.guard';
-
-@Injectable()
-export class BusinessHoursGuard extends ExGuardNestGuard {
-  public async checkPermissions(context: GuardContext) {
-    const user = context.request.user;
-    
-    // Only allow access during business hours (9 AM - 5 PM)
-    const hour = new Date().getHours();
-    if (hour < 9 || hour > 17) {
-      return {
-        allowed: false,
-        error: 'Access only allowed during business hours (9 AM - 5 PM)'
-      };
-    }
-
-    // Check basic permissions
-    return this.exGuard.requirePermissions(context, ['business:access']);
-  }
-}
-
-// Usage
-@Controller('business')
-@UseGuards(BusinessHoursGuard)
-export class BusinessController {
-  @Get()
-  async getBusinessData(@Request() req) {
-    return { success: true, data: [], message: 'Business data' };
-  }
-}
-```
-
-### **Dynamic Resource Protection**
-
-#### **Resource-Specific Permissions**
-```typescript
-@Controller('resources')
-export class ResourceController {
-  @Get(':resource')
-  @UseGuards(createPermissionGuard(['resources:read']))
-  async getResource(@Param('resource') resource: string, @Request() req) {
-    // Check if user has permission for this specific resource
-    const hasPermission = req.user?.permissions?.includes(`${resource}:read`);
-    
-    if (!hasPermission) {
-      return { success: false, error: 'No access to this resource' };
-    }
-    
-    return { success: true, data: { resource } };
-  }
-
-  @Post(':resource')
-  @UseGuards(createPermissionGuard(['resources:create']))
-  async createResource(
-    @Param('resource') resource: string,
-    @Body() createDto: any,
-    @Request() req
-  ) {
-    return { 
-      success: true, 
-      data: { resource, ...createDto },
-      message: `${resource} created successfully`
-    };
-  }
-}
-```
-
-### **Field Office Protection**
-
-#### **Location-Based Access**
-```typescript
-@Controller('field-offices')
-export class FieldOfficeController {
-  @Get()
-  @UseGuards(createPermissionGuard(['field-offices:read']))
-  async getFieldOffices(@Request() req) {
-    // Only show field offices user has access to
-    const userFieldOffices = req.user?.fieldOffices || [];
-    return { success: true, data: userFieldOffices };
-  }
-
-  @Get(':officeId')
-  @UseGuards(createPermissionGuard(['field-offices:manage']))
-  async getFieldOffice(
-    @Param('officeId') officeId: string,
-    @Request() req
-  ) {
-    // Check if user has access to this specific field office
-    const userFieldOffices = req.user?.fieldOffices || [];
-    const hasAccess = userFieldOffices.includes(officeId);
-    
-    if (!hasAccess) {
-      return { success: false, error: 'No access to this field office' };
-    }
-    
-    return { success: true, data: { officeId } };
-  }
-}
-```
-
-### **API Response Format**
-
-#### **Standardized Responses**
-```typescript
-@Controller('api')
-export class ApiController {
-  @Get('protected')
-  @UseGuards(createPermissionGuard(['api:access']))
-  async getProtectedData(@Request() req) {
-    return {
-      success: true,
-      data: {
-        message: 'Protected data accessed successfully',
-        user: req.user,
-        timestamp: new Date().toISOString()
-      },
-      meta: {
-        permissions: req.user?.permissions,
-        roles: req.user?.roles,
-        fieldOffices: req.user?.fieldOffices
+      if (requireAll) {
+        if (!permissions.every(p => userPermissions.includes(p))) {
+          throw new ForbiddenException('Insufficient permissions');
+        }
+      } else {
+        if (!permissions.some(p => userPermissions.includes(p))) {
+          throw new ForbiddenException('Insufficient permissions');
+        }
       }
-    };
-  }
-
-  @Get('forbidden')
-  async getForbiddenData() {
-    // This endpoint is not protected - for testing
-    return {
-      success: false,
-      error: 'This endpoint requires authentication',
-      code: 'AUTH_REQUIRED'
-    };
-  }
-}
-```
-
-## 📚 Documentation
-
-- **[NestJS Setup Guide](./examples/NESTJS-SETUP.md)** - Complete NestJS integration guide
-- **[Backend Protection Guide](./README-BACKEND-PROTECTION.md)** - Complete usage guide
-- **[Integration & Publishing](./README-INTEGRATION.md)** - Setup, integration, and publishing instructions
-- **[Enhanced Features](./README-ENHANCED.md)** - Caching and realtime features
-
-## 🎯 Common NestJS Use Cases
-
-### Admin Panel Protection
-
-```typescript
-@Controller('admin')
-@UseGuards(createRoleGuard(['Admin']))
-export class AdminController {
-  @Get('users')
-  async getUsers() {
-    return { success: true, data: [] };
-  }
-}
-```
-
-### Multi-tenant Applications
-
-```typescript
-@Controller('field-offices')
-export class FieldOfficesController {
-  @Get(':officeId/data')
-  @UseGuards(new (class extends ExGuardNestGuard {
-    protected async checkPermissions(context: any) {
-      const officeId = context.request.params.officeId;
-      return this.exGuard.requireFieldOffices(context, [officeId]);
     }
-  })(this.exGuard))
-  async getOfficeData(@Param('officeId') officeId: string) {
-    return { success: true, data: { officeId } };
-  }
-}
-```
 
-### API Versioning
+    request.user = authResult.user;
+    return true;
+  }
 
-```typescript
-@Controller({ path: 'events', version: '1' })
-@UseGuards(createPermissionGuard(['events:read:v1']))
-export class EventsV1Controller {
-  @Get()
-  async getEventsV1() {
-    return { success: true, data: [], version: 1 };
+  private extractToken(request: any): string | null {
+    const auth = request.headers?.authorization;
+    return auth?.startsWith('Bearer ') ? auth.substring(7) : request.headers?.['x-access-token'] || null;
   }
 }
 
-@Controller({ path: 'events', version: '2' })
-@UseGuards(createPermissionGuard(['events:read:v2']))
-export class EventsV2Controller {
-  @Get()
-  async getEventsV2() {
-    return { success: true, data: [], version: 2 };
-  }
+export function RequirePermissions(permissions: string[], requireAll = false) {
+  return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+    Reflect.defineMetadata(EXGUARD_PERMISSIONS_KEY, { permissions, requireAll }, descriptor.value);
+  };
 }
 ```
 
-## 🔄 Migration from v1.x to v2.x
+Create `src/exguard/exguard.module.ts`:
 
 ```typescript
-// v1.x (old)
+import { Module, Global, DynamicModule } from '@nestjs/common';
 import { ExGuardBackend } from 'exguard-backend';
-const guard = new ExGuardBackend({ apiUrl: 'http://localhost:3000' });
-
-// v2.x (new) - NestJS Integration
-import { Guard } from 'exguard-backend';
-import { ExGuardNestGuard } from './exguard.guard';
 
-@Injectable()
+@Global()
+@Module({})
 export class ExGuardModule {
-  constructor() {
-    this.exGuard = new Guard({ 
-      apiUrl: 'http://localhost:3000',
-      cache: { enabled: true }, // New: caching
+  static forRoot(options: { baseUrl: string; apiKey: string; cache?: { enabled?: boolean; ttl?: number } }): DynamicModule {
+    const exGuard = new ExGuardBackend({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      cache: options.cache || { enabled: true, ttl: 300000 },
     });
-  }
-}
-
-@Controller('events')
-@UseGuards(ExGuardNestGuard)
-export class EventsController {
-  // Now protected with decorators!
-}
-```
-
-## 🚀 Deployment & Production
-
-### Docker Configuration
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --only=production
-
-COPY dist/ ./dist/
-
-# Environment variables
-ENV EXGUARD_CACHE_ENABLED=true
-ENV EXGUARD_CACHE_TTL=300000
 
-EXPOSE 3000
-
-CMD ["node", "dist/main.js"]
-```
-
-### Kubernetes Deployment
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: nestjs-app
-spec:
-  template:
-    spec:
-      containers:
-      - name: nestjs-app
-        image: your-registry/nestjs-app:latest
-        env:
-        - name: EXGUARD_API_URL
-          value: "https://api.your-domain.com"
-        - name: EXGUARD_CACHE_ENABLED
-          value: "true"
-        - name: EXGUARD_CACHE_TTL
-          value: "300000"
-```
-
-## 📈 Monitoring & Debugging
-
-### Cache Statistics Endpoint
-
-```typescript
-@Controller('admin')
-@UseGuards(createRoleGuard(['Admin']))
-export class AdminController {
-  constructor(private exGuard: Guard) {}
-
-  @Get('cache-stats')
-  async getCacheStats() {
-    const stats = this.exGuard.getExGuard().getCacheStats();
     return {
-      success: true,
-      data: {
-        cacheSize: stats.size,
-        cacheKeys: stats.keys,
-        timestamp: new Date().toISOString(),
-      },
+      module: ExGuardModule,
+      providers: [
+        { provide: 'EXGUARD_INSTANCE', useValue: exGuard },
+      ],
+      exports: ['EXGUARD_INSTANCE'],
     };
   }
 }
 ```
 
-### Logging Integration
-
-```typescript
-import { Logger } from '@nestjs/common';
-
-@Injectable()
-export class ExGuardNestGuard implements CanActivate {
-  private readonly logger = new Logger(ExGuardNestGuard.name);
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const request = context.switchToHttp().getRequest();
-    
-    this.logger.log(`Checking access for ${request.method} ${request.url}`);
-    
-    const result = await this.checkPermissions(guardContext);
-    
-    if (result.allowed) {
-      this.logger.log(`Access granted for user ${result.user?.user?.id}`);
-    } else {
-      this.logger.warn(`Access denied: ${result.error}`);
-    }
-    
-    return result.allowed;
-  }
-}
-```
-
-## � Security Best Practices
-
-### Token Validation
+### 2. Configure AppModule
 
 ```typescript
-@Injectable()
-export class ExGuardNestGuard implements CanActivate {
-  protected extractToken(request: any): string | null {
-    const authHeader = request.headers?.authorization;
-    
-    if (!authHeader?.startsWith('Bearer ')) {
-      return null;
-    }
-    
-    const token = authHeader.substring(7);
-    
-    // Additional validation
-    if (token.length < 10) {
-      return null;
-    }
-    
-    return token;
-  }
-}
-```
-
-### Error Handling
+import { Module } from '@nestjs/common';
+import { ExGuardModule } from './exguard/exguard.module';
 
-```typescript
-@Injectable()
-export class ExGuardNestGuard implements CanActivate {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    try {
-      // ... permission checking logic
-    } catch (error) {
-      console.error('ExGuard error:', error);
-      
-      // Don't expose internal errors
-      throw new ForbiddenException('Access check failed');
-    }
-  }
-}
+@Module({
+  imports: [
+    ExGuardModule.forRoot({
+      baseUrl: 'https://api.exguard.com',
+      apiKey: process.env.EXGUARD_API_KEY,
+      cache: { enabled: true, ttl: 300000 },
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-## 📊 Performance Benchmarks
-
-Real-world performance metrics with NestJS:
-
-| Scenario | Requests/sec | Avg Response Time | Cache Hit Rate |
-|----------|--------------|-------------------|----------------|
-| Single Permission | 2,000 | 5ms | 95% |
-| Multiple Permissions | 1,800 | 8ms | 92% |
-| Role Checks | 2,200 | 4ms | 96% |
-| Complex Requirements | 1,500 | 12ms | 88% |
-
-## 🎉 Summary
-
-Your NestJS application now has:
-
-✅ **Enterprise-grade RBAC protection** with decorators  
-✅ **95%+ performance improvement** through intelligent caching  
-✅ **Realtime cache invalidation** for data consistency  
-✅ **Comprehensive testing support** with Jest  
-✅ **Production-ready deployment** configurations  
-✅ **Detailed monitoring and debugging** capabilities  
-
-**Perfect for production NestJS applications!** 🚀
-
----
-
-**Need help? Check out our [NestJS Setup Guide](./examples/NESTJS-SETUP.md) for detailed instructions.**
-
-## API Reference
-
-### Constructor
+### 3. Use in Controllers
 
 ```typescript
-new ExGuardBackend(config: ExGuardConfig)
-```
-
-**Config:**
-- `apiUrl` (string): Base URL of your Guard API
-- `timeout` (number, optional): Request timeout in milliseconds (default: 10000)
+import { Controller, Get, Post, UseGuards } from '@nestjs/common';
+import { ExGuardPermissionGuard, RequirePermissions } from '@/exguard/exguard.guard';
 
-### Methods
+@Controller('items')
+@UseGuards(ExGuardPermissionGuard)
+export class ItemsController {
+  
+  @Get()
+  @RequirePermissions(['item:read'])
+  findAll() { }
 
-#### `getUserAccess(token: string): Promise<UserAccessResponse>`
+  @Post()
+  @RequirePermissions(['item:create'])
+  create() { }
 
-Get complete user access information including roles, permissions, and field offices.
+  @Get('drafts')
+  @RequirePermissions(['item:read_draft', 'item:admin']) // ANY of these
+  findDrafts() { }
 
-**Returns:**
-```typescript
-{
-  user: User,
-  groups: string[],
-  roles: string[],
-  module: string[],
-  modules: ModulePermission[],
-  fieldOffices: string[]
+  @Delete(':id')
+  @RequirePermissions(['item:delete', 'admin'], true) // ALL of these
+  delete() { }
 }
 ```
 
-#### `hasPermission(token: string, permission: string): Promise<boolean>`
-
-Check if user has a specific permission.
-
-**Example:**
-```typescript
-const canCreateEvent = await exGuard.hasPermission(token, 'events:create');
-```
-
-#### `hasRole(token: string, role: string): Promise<boolean>`
-
-Check if user has a specific role.
-
-**Example:**
-```typescript
-const isEventManager = await exGuard.hasRole(token, 'Event Manager');
-```
-
-#### `getModulePermissions(token: string, moduleKey: string): Promise<string[]>`
+## Token Format
 
-Get all permissions for a specific module.
+The guard extracts token from:
+- `Authorization: Bearer <token>` header
+- `x-access-token` header
 
-**Example:**
-```typescript
-const eventPermissions = await exGuard.getModulePermissions(token, 'events');
-// Returns: ['events:create', 'events:read', 'events:update', 'events:delete']
-```
-
-#### `getUserRoles(token: string): Promise<string[]>`
-
-Get all user roles.
-
-**Example:**
-```typescript
-const roles = await exGuard.getUserRoles(token);
-// Returns: ['Event Manager', 'Viewer']
-```
+## Configuration
 
-#### `getUserFieldOffices(token: string): Promise<string[]>`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| baseUrl | string | required | ExGuard API URL |
+| apiKey | string | required | Your API key |
+| cache.enabled | boolean | true | Enable caching |
+| cache.ttl | number | 300000 | Cache TTL in ms (5 min) |
 
-Get all user field offices.
+## Express/Fastify (Non-NestJS)
 
-**Example:**
 ```typescript
-const fieldOffices = await exGuard.getUserFieldOffices(token);
-// Returns: ['FO-MIMAROPA', 'FO-NCR']
-```
-
-## Usage Examples
+import { createExGuardExpress } from 'exguard-backend';
 
-### Express.js Middleware
-
-```typescript
-import express from 'express';
-import { ExGuardBackend } from 'exguard-backend';
-
-const app = express();
-const exGuard = new ExGuardBackend({
-  apiUrl: process.env.GUARD_API_URL || 'http://localhost:3001'
+const guard = createExGuardExpress({
+  baseUrl: 'https://api.exguard.com',
+  apiKey: process.env.EXGUARD_API_KEY,
 });
 
-// Middleware to check permissions
-const requirePermission = (permission: string) => {
-  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
-    const token = req.headers.authorization?.replace('Bearer ', '');
-    
-    if (!token) {
-      return res.status(401).json({ error: 'No token provided' });
-    }
-
-    try {
-      const hasPermission = await exGuard.hasPermission(token, permission);
-      if (!hasPermission) {
-        return res.status(403).json({ error: 'Insufficient permissions' });
-      }
-      next();
-    } catch (error) {
-      return res.status(401).json({ error: 'Invalid token' });
-    }
-  };
-};
-
-// Use in routes
-app.post('/events', requirePermission('events:create'), (req, res) => {
-  // Your route logic here
-});
+// Use as middleware
+app.use('/api', guard.requirePermissions(['item:read']));
 ```
 
-### NestJS Guard
-
-```typescript
-import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
-import { ExGuardBackend } from 'exguard-backend';
-
-@Injectable()
-export class PermissionGuard implements CanActivate {
-  private exGuard = new ExGuardBackend({
-    apiUrl: process.env.GUARD_API_URL
-  });
-
-  constructor(private requiredPermission: string) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const request = context.switchToHttp().getRequest();
-    const token = request.headers.authorization?.replace('Bearer ', '');
-    
-    if (!token) {
-      return false;
-    }
-
-    return await this.exGuard.hasPermission(token, this.requiredPermission);
-  }
-}
-
-// Usage in controller
-@Get('events')
-@UseGuards(new PermissionGuard('events:read'))
-async getEvents() {
-  // Your logic here
-}
-```
-
-## Error Handling
-
-The SDK throws specific errors for different scenarios:
-
-- **Unauthorized**: Invalid or expired token (401)
-- **API Error**: General API errors with detailed messages
-- **Network Error**: Connection issues
-
-Always wrap SDK calls in try-catch blocks for proper error handling.
-
 ## License
 
 MIT