exguard-backend 1.0.4 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exguard-backend",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -19,8 +19,12 @@
   },
   "files": [
     "dist",
+    "scripts",
     "README.md"
   ],
+  "bin": {
+    "exguard-backend": "scripts/setup-nestjs.cjs"
+  },
   "keywords": [
     "exguard",
     "rbac",
@@ -47,7 +51,7 @@
     "test:watch": "node --test --watch",
     "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "prebuild": "npm run clean",
-    "setup-nestjs": "node scripts/setup-nestjs.js",
-    "create-example": "node scripts/create-example.js"
+    "setup-nestjs": "node scripts/setup-nestjs.cjs",
+    "create-example": "node scripts/create-example.cjs"
   }
 }

package/scripts/create-example.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+/**
+ * Create Example Controller for ExGuard
+ * 
+ * Usage:
+ *   npx exguard-backend create-example
+ *   OR
+ *   node node_modules/exguard-backend/scripts/create-example.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function logSuccess(message) {
+  log(`✅ ${message}`, 'green');
+}
+
+function logInfo(message) {
+  log(`ℹ️  ${message}`, 'cyan');
+}
+
+// Create example controller
+function createExampleController() {
+  const controllerContent = `import { 
+  Controller, 
+  Get, 
+  Post, 
+  Put, 
+  Delete,
+  Body, 
+  Param,
+  UseGuards, 
+  Request 
+} from '@nestjs/common';
+import { 
+  RequirePermissions, 
+  RequireRoles,
+  RequireModules 
+} from '../exguard/exguard.decorators';
+import { 
+  ExGuardPermissionGuard, 
+  createPermissionGuard,
+  createRoleGuard,
+  createModuleGuard
+} from '../exguard/exguard.guard';
+
+@Controller('api/example')
+export class ExampleController {
+  @Get()
+  @UseGuards(ExGuardPermissionGuard) // Requires 'read' permission
+  async getItems(@Request() req) {
+    return { 
+      success: true, 
+      data: [],
+      user: req.user,
+      message: 'Items retrieved successfully' 
+    };
+  }
+
+  @Post()
+  @RequirePermissions(['items:create']) // Using decorator
+  @UseGuards(createPermissionGuard(['items:create']))
+  async createItem(@Body() createDto: any, @Request() req) {
+    return { 
+      success: true, 
+      data: createDto,
+      user: req.user,
+      message: 'Item created successfully' 
+    };
+  }
+
+  @Put(':id')
+  @UseGuards(createPermissionGuard(['items:update'], true)) // Require both permissions
+  async updateItem(@Param('id') id: string, @Body() updateDto: any, @Request() req) {
+    return { 
+      success: true, 
+      data: { id, ...updateDto },
+      user: req.user,
+      message: 'Item updated successfully' 
+    };
+  }
+
+  @Delete(':id')
+  @RequireRoles(['Admin', 'Manager']) // Using decorator
+  @UseGuards(createRoleGuard(['Admin', 'Manager']))
+  async deleteItem(@Param('id') id: string, @Request() req) {
+    return { 
+      success: true, 
+      message: \`Item \${id} deleted successfully\`,
+      user: req.user 
+    };
+  }
+
+  @Get('reports')
+  @RequireModules(['reporting']) // Using decorator
+  @UseGuards(createModuleGuard(['reporting']))
+  async getReports(@Request() req) {
+    return { 
+      success: true, 
+      data: { reports: [], total: 0 },
+      user: req.user,
+      message: 'Reports retrieved successfully' 
+    };
+  }
+
+  @Get('admin/dashboard')
+  @UseGuards(createRoleGuard(['Admin']))
+  async getAdminDashboard(@Request() req) {
+    return { 
+      success: true, 
+      data: { 
+        totalUsers: 100,
+        activeUsers: 85,
+        totalItems: 500 
+      },
+      user: req.user,
+      message: 'Admin dashboard data retrieved' 
+    };
+  }
+
+  @Get('complex')
+  @UseGuards(new (class extends ExGuardPermissionGuard {
+    protected async checkPermissions(context: any) {
+      return this.exGuard.require(context, {
+        permissions: ['complex:access'],
+        roles: ['Manager'],
+        modules: ['analytics'],
+        requireAll: true // Must satisfy ALL conditions
+      });
+    }
+  })(this.exGuard))
+  async getComplexData(@Request() req) {
+    return { 
+      success: true, 
+      data: { complexData: '...' },
+      user: req.user,
+      message: 'Complex data accessed successfully' 
+    };
+  }
+}
+`;
+
+  const controllerPath = path.join(process.cwd(), 'src/api/example/example.controller.ts');
+  
+  // Create directories if they don't exist
+  const apiDir = path.join(process.cwd(), 'src/api');
+  const exampleDir = path.join(process.cwd(), 'src/api/example');
+  
+  if (!fs.existsSync(apiDir)) {
+    fs.mkdirSync(apiDir, { recursive: true });
+    logSuccess('Created api directory');
+  }
+  
+  if (!fs.existsSync(exampleDir)) {
+    fs.mkdirSync(exampleDir, { recursive: true });
+    logSuccess('Created example directory');
+  }
+
+  if (fs.existsSync(controllerPath)) {
+    log('⚠️  Example controller already exists. Skipping creation.', 'yellow');
+    return;
+  }
+
+  fs.writeFileSync(controllerPath, controllerContent);
+  logSuccess('Created example controller at src/api/example/example.controller.ts');
+  
+  logInfo('\n📋 Example controller features:');
+  logInfo('• Basic CRUD operations with permission protection');
+  logInfo('• Role-based protection for admin operations');
+  logInfo('• Module-based protection for reports');
+  logInfo('• Complex multi-requirement protection');
+  logInfo('• Decorator usage examples');
+  logInfo('• Dynamic guard factory usage');
+  
+  logInfo('\n🎯 Next steps:');
+  logInfo('1. Update your app.module.ts to import ExampleController');
+  logInfo('2. Start your application: npm run start:dev');
+  logInfo('3. Test the endpoints with different user permissions');
+  logInfo('4. Check the user data attached to requests');
+}
+
+// Run if called directly
+if (require.main === module) {
+  log('🚀 Creating ExGuard Example Controller', 'cyan');
+  createExampleController();
+}
+
+module.exports = { createExampleController };

package/scripts/setup-nestjs.cjs

@@ -0,0 +1,535 @@
+#!/usr/bin/env node
+
+/**
+ * Automatic ExGuard Module Setup for NestJS
+ * 
+ * Usage:
+ *   npx exguard-backend
+ *   npx exguard-backend setup-nestjs
+ *   OR
+ *   node node_modules/exguard-backend/scripts/setup-nestjs.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ANSI colors for better output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function logStep(step, message) {
+  log(`\n🔧 Step ${step}: ${message}`, 'cyan');
+}
+
+function logSuccess(message) {
+  log(`✅ ${message}`, 'green');
+}
+
+function logWarning(message) {
+  log(`⚠️  ${message}`, 'yellow');
+}
+
+function logError(message) {
+  log(`❌ ${message}`, 'red');
+}
+
+function logInfo(message) {
+  log(`ℹ️  ${message}`, 'blue');
+}
+
+// Check if we're in a NestJS project
+function checkNestJSProject() {
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  
+  if (!fs.existsSync(packageJsonPath)) {
+    logError('package.json not found. Please run this command in a NestJS project root.');
+    process.exit(1);
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const dependencies = { ...packageJson.dependencies, ...packageJson.devDependencies };
+  
+  const nestPackages = Object.keys(dependencies).filter(dep => 
+    dep.startsWith('@nestjs/') || dep === 'nestjs'
+  );
+
+  if (nestPackages.length === 0) {
+    logError('No NestJS packages found. Please run this command in a NestJS project.');
+    process.exit(1);
+  }
+
+  logSuccess(`NestJS project detected with packages: ${nestPackages.join(', ')}`);
+  return true;
+}
+
+// Create exguard directory structure
+function createDirectoryStructure() {
+  logStep(1, 'Creating ExGuard directory structure');
+
+  const directories = [
+    'src/exguard',
+    'src/exguard/guards',
+    'src/exguard/decorators',
+    'src/exguard/interceptors'
+  ];
+
+  directories.forEach(dir => {
+    const fullPath = path.join(process.cwd(), dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+      logSuccess(`Created directory: ${dir}`);
+    } else {
+      logWarning(`Directory already exists: ${dir}`);
+    }
+  });
+}
+
+// Create ExGuard Module
+function createExGuardModule() {
+  logStep(2, 'Creating ExGuard Module');
+
+  const moduleContent = `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: process.env.EXGUARD_CACHE_ENABLED !== 'false',
+          ttl: parseInt(process.env.EXGUARD_CACHE_TTL) || 300000, // 5 minutes
+        },
+        realtime: {
+          enabled: process.env.EXGUARD_REALTIME_ENABLED === 'true',
+          url: process.env.EXGUARD_REALTIME_URL,
+          token: process.env.EXGUARD_SERVICE_TOKEN,
+        },
+      }),
+    },
+  ],
+  exports: [Guard],
+})
+export class ExGuardModule {}
+`;
+
+  const modulePath = path.join(process.cwd(), 'src/exguard/exguard.module.ts');
+  
+  if (fs.existsSync(modulePath)) {
+    logWarning('ExGuardModule already exists. Skipping creation.');
+    return;
+  }
+
+  fs.writeFileSync(modulePath, moduleContent);
+  logSuccess('Created ExGuardModule');
+}
+
+// Create ExGuard Guards
+function createExGuardGuards() {
+  logStep(3, 'Creating ExGuard Guards');
+
+  const guardContent = `import { Injectable, CanActivate, ExecutionContext, ForbiddenException, UnauthorizedException } from '@nestjs/common';
+import { Guard, GuardContext } from 'exguard-backend';
+
+@Injectable()
+export class ExGuardNestGuard implements CanActivate {
+  constructor(protected exGuard: Guard) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest();
+    const token = this.extractToken(request);
+    
+    if (!token) {
+      throw new UnauthorizedException('No authentication token provided');
+    }
+
+    const guardContext: GuardContext = {
+      token,
+      request,
+    };
+
+    const result = await this.checkPermissions(guardContext);
+    
+    if (!result.allowed) {
+      throw new ForbiddenException(result.error || 'Access denied');
+    }
+
+    request.user = result.user;
+    return true;
+  }
+
+  protected async checkPermissions(context: GuardContext) {
+    return this.exGuard.authenticate(context);
+  }
+
+  protected extractToken(request: any): string | null {
+    const authHeader = request.headers?.authorization;
+    if (authHeader?.startsWith('Bearer ')) {
+      return authHeader.substring(7);
+    }
+    return null;
+  }
+}
+
+@Injectable()
+export class ExGuardPermissionGuard extends ExGuardNestGuard {
+  protected async checkPermissions(context: GuardContext) {
+    return this.exGuard.requirePermissions(context, ['read']);
+  }
+}
+
+@Injectable()
+export class ExGuardRoleGuard extends ExGuardNestGuard {
+  protected async checkPermissions(context: GuardContext) {
+    return this.exGuard.requireRoles(context, ['Admin']);
+  }
+}
+
+// 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 });
+    }
+  };
+}
+
+export function createRoleGuard(roles: string[], requireAll = false) {
+  return class extends ExGuardNestGuard {
+    protected async checkPermissions(context: GuardContext) {
+      return this.exGuard.requireRoles(context, roles, { requireAll });
+    }
+  };
+}
+
+export function createModuleGuard(modules: string[], requireAll = false) {
+  return class extends ExGuardNestGuard {
+    protected async checkPermissions(context: GuardContext) {
+      return this.exGuard.requireModules(context, modules, { requireAll });
+    }
+  };
+}
+`;
+
+  const guardPath = path.join(process.cwd(), 'src/exguard/exguard.guard.ts');
+  
+  if (fs.existsSync(guardPath)) {
+    logWarning('ExGuard guards already exist. Skipping creation.');
+    return;
+  }
+
+  fs.writeFileSync(guardPath, guardContent);
+  logSuccess('Created ExGuard guards');
+}
+
+// Create ExGuard Decorators
+function createExGuardDecorators() {
+  logStep(4, 'Creating ExGuard Decorators');
+
+  const decoratorContent = `import { SetMetadata } from '@nestjs/common';
+import { createPermissionGuard, createRoleGuard, createModuleGuard } from './exguard.guard';
+
+// Metadata keys
+export const EXGUARD_PERMISSIONS_KEY = 'exguard_permissions';
+export const EXGUARD_ROLES_KEY = 'exguard_roles';
+export const EXGUARD_MODULES_KEY = 'exguard_modules';
+export const EXGUARD_FIELD_OFFICES_KEY = 'exguard_field_offices';
+
+// Permission decorator
+export const RequirePermissions = (permissions: string[], requireAll = false) => {
+  return SetMetadata(EXGUARD_PERMISSIONS_KEY, { permissions, requireAll });
+};
+
+// Role decorator
+export const RequireRoles = (roles: string[], requireAll = false) => {
+  return SetMetadata(EXGUARD_ROLES_KEY, { roles, requireAll });
+};
+
+// Module decorator
+export const RequireModules = (modules: string[], requireAll = false) => {
+  return SetMetadata(EXGUARD_MODULES_KEY, { modules, requireAll });
+};
+
+// Field office decorator
+export const RequireFieldOffices = (fieldOffices: string[], requireAll = false) => {
+  return SetMetadata(EXGUARD_FIELD_OFFICES_KEY, { fieldOffices, requireAll });
+};
+
+// Combined decorator for complex requirements
+export const Require = (requirements: {
+  permissions?: string[];
+  roles?: string[];
+  modules?: string[];
+  fieldOffices?: string[];
+  requireAll?: boolean;
+}) => {
+  return (target: any) => {
+    if (requirements.permissions) {
+      SetMetadata(EXGUARD_PERMISSIONS_KEY, { 
+        permissions: requirements.permissions, 
+        requireAll: requirements.requireAll || false 
+      })(target);
+    }
+    if (requirements.roles) {
+      SetMetadata(EXGUARD_ROLES_KEY, { 
+        roles: requirements.roles, 
+        requireAll: requirements.requireAll || false 
+      })(target);
+    }
+    if (requirements.modules) {
+      SetMetadata(EXGUARD_MODULES_KEY, { 
+        modules: requirements.modules, 
+        requireAll: requirements.requireAll || false 
+      })(target);
+    }
+    if (requirements.fieldOffices) {
+      SetMetadata(EXGUARD_FIELD_OFFICES_KEY, { 
+        fieldOffices: requirements.fieldOffices, 
+        requireAll: requirements.requireAll || false 
+      })(target);
+    }
+  };
+};
+`;
+
+  const decoratorPath = path.join(process.cwd(), 'src/exguard/exguard.decorators.ts');
+  
+  if (fs.existsSync(decoratorPath)) {
+    logWarning('ExGuard decorators already exist. Skipping creation.');
+    return;
+  }
+
+  fs.writeFileSync(decoratorPath, decoratorContent);
+  logSuccess('Created ExGuard decorators');
+}
+
+// Create example controller
+function createExampleController() {
+  logStep(5, 'Creating Example Controller');
+
+  const controllerContent = `import { 
+  Controller, 
+  Get, 
+  Post, 
+  Body, 
+  UseGuards, 
+  Request 
+} from '@nestjs/common';
+import { 
+  RequirePermissions, 
+  RequireRoles,
+  RequireModules 
+} from '../exguard/exguard.decorators';
+import { 
+  ExGuardPermissionGuard, 
+  createPermissionGuard 
+} from '../exguard/exguard.guard';
+
+@Controller('events')
+@UseGuards(ExGuardPermissionGuard) // Requires 'read' permission
+export class EventsController {
+  @Get()
+  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 };
+  }
+
+  @Get('admin')
+  @RequireRoles(['Admin']) // Using decorator
+  @UseGuards(createRoleGuard(['Admin']))
+  async getAdminEvents(@Request() req) {
+    return { success: true, data: [], message: 'Admin events' };
+  }
+
+  @Get('reports')
+  @RequireModules(['reporting']) // Using decorator
+  @UseGuards(createModuleGuard(['reporting']))
+  async getReports(@Request() req) {
+    return { success: true, data: [], message: 'Reports data' };
+  }
+}
+`;
+
+  const controllerPath = path.join(process.cwd(), 'src/events/events.controller.ts');
+  
+  // Check if events directory exists
+  const eventsDir = path.join(process.cwd(), 'src/events');
+  if (!fs.existsSync(eventsDir)) {
+    fs.mkdirSync(eventsDir, { recursive: true });
+    logSuccess('Created events directory');
+  }
+
+  if (fs.existsSync(controllerPath)) {
+    logWarning('Example controller already exists. Skipping creation.');
+    return;
+  }
+
+  fs.writeFileSync(controllerPath, controllerContent);
+  logSuccess('Created example controller');
+}
+
+// Update app module
+function updateAppModule() {
+  logStep(6, 'Updating App Module');
+
+  const appModulePath = path.join(process.cwd(), 'src/app.module.ts');
+  
+  if (!fs.existsSync(appModulePath)) {
+    logWarning('app.module.ts not found. Please manually import ExGuardModule.');
+    return;
+  }
+
+  let appModuleContent = fs.readFileSync(appModulePath, 'utf8');
+
+  // Check if ExGuardModule is already imported
+  if (appModuleContent.includes('ExGuardModule')) {
+    logWarning('ExGuardModule already imported in app.module.ts');
+    return;
+  }
+
+  // Add import
+  const importMatch = appModuleContent.match(/import\s*\{[^}]*\}\s*from\s*['"][^'"]*['"];?\s*/m);
+  if (importMatch) {
+    const lastImport = importMatch[0];
+    const newImport = lastImport.replace(/;?\s*$/, '') + ',\n  ExGuardModule from \'./exguard/exguard.module\';\n';
+    appModuleContent = appModuleContent.replace(lastImport, newImport);
+  } else {
+    // Add import at the top
+    appModuleContent = `import { ExGuardModule } from './exguard/exguard.module';\n\n${appModuleContent}`;
+  }
+
+  // Add to imports array
+  const importsMatch = appModuleContent.match(/@Module\s*\(\s*\{\s*imports:\s*\[([^\]]*)\]/m);
+  if (importsMatch) {
+    const importsContent = importsMatch[1];
+    const newImportsContent = importsContent.trim() + ',\n    ExGuardModule';
+    appModuleContent = appModuleContent.replace(importsMatch[0], `@Module({\n  imports: [${newImportsContent}]`);
+  }
+
+  fs.writeFileSync(appModulePath, appModuleContent);
+  logSuccess('Updated app.module.ts with ExGuardModule');
+}
+
+// Create environment variables
+function createEnvironmentFile() {
+  logStep(7, 'Creating Environment Variables');
+
+  const envContent = `# ExGuard Configuration
+EXGUARD_API_URL=http://localhost:3000
+EXGUARD_CACHE_ENABLED=true
+EXGUARD_CACHE_TTL=300000
+
+# Optional Realtime Configuration
+EXGUARD_REALTIME_ENABLED=false
+EXGUARD_REALTIME_URL=ws://localhost:3000/realtime
+EXGUARD_SERVICE_TOKEN=your-service-jwt-token
+`;
+
+  const envPath = path.join(process.cwd(), '.env');
+  
+  if (fs.existsSync(envPath)) {
+    // Append if not already present
+    const existingEnv = fs.readFileSync(envPath, 'utf8');
+    if (!existingEnv.includes('EXGUARD_API_URL')) {
+      fs.appendFileSync(envPath, '\n\n# ExGuard Configuration\n' + envContent);
+      logSuccess('Appended ExGuard configuration to .env');
+    } else {
+      logWarning('ExGuard configuration already exists in .env');
+    }
+  } else {
+    fs.writeFileSync(envPath, envContent);
+    logSuccess('Created .env with ExGuard configuration');
+  }
+}
+
+// Update package.json scripts
+function updatePackageScripts() {
+  logStep(8, 'Updating Package Scripts');
+
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+  const scriptsToAdd = {
+    'exguard:setup': 'node node_modules/exguard-backend/scripts/setup-nestjs.js',
+    'exguard:example': 'node node_modules/exguard-backend/scripts/create-example.js'
+  };
+
+  if (!packageJson.scripts) {
+    packageJson.scripts = {};
+  }
+
+  Object.entries(scriptsToAdd).forEach(([script, command]) => {
+    if (!packageJson.scripts[script]) {
+      packageJson.scripts[script] = command;
+      logSuccess(`Added script: ${script}`);
+    } else {
+      logWarning(`Script already exists: ${script}`);
+    }
+  });
+
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+  logSuccess('Updated package.json scripts');
+}
+
+// Main setup function
+async function setupExGuard() {
+  log('🚀 ExGuard NestJS Automatic Setup', 'bright');
+  log('This script will automatically set up ExGuard in your NestJS project.\n');
+
+  try {
+    checkNestJSProject();
+    createDirectoryStructure();
+    createExGuardModule();
+    createExGuardGuards();
+    createExGuardDecorators();
+    createExampleController();
+    updateAppModule();
+    createEnvironmentFile();
+    updatePackageScripts();
+
+    log('\n🎉 ExGuard setup completed successfully!', 'green');
+    log('\n📋 Next steps:', 'cyan');
+    log('1. Review the generated files in src/exguard/', 'blue');
+    log('2. Check the example controller in src/events/', 'blue');
+    log('3. Update your .env file with your ExGuard API URL', 'blue');
+    log('4. Start your application: npm run start:dev', 'blue');
+    log('5. Test the protected endpoints', 'blue');
+
+    log('\n📚 Documentation:', 'cyan');
+    log('- Main README: node_modules/exguard-backend/README.md', 'blue');
+    log('- NestJS Guide: node_modules/exguard-backend/examples/NESTJS-SETUP.md', 'blue');
+
+  } catch (error) {
+    logError(`Setup failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Run setup if called directly
+if (require.main === module) {
+  setupExGuard();
+}
+
+module.exports = { setupExGuard };