exguard-backend 1.1.0 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # ExGuard Backend SDK
 
-Simple RBAC/ABAC permission guard for NestJS.
+Simple RBAC permission guard for NestJS.
 
 ## Installation
 
@@ -8,11 +8,23 @@ Simple RBAC/ABAC permission guard for NestJS.
 npm install exguard-backend
 ```
 
-## Quick Setup
+## Quick Setup (Auto)
 
-### 1. Copy Guard Files
+Run this command in your NestJS project root:
 
-Create `src/exguard/exguard.guard.ts`:
+```bash
+npx exguard-backend setup
+```
+
+This creates:
+- `src/exguard/exguard.guard.ts` - The permission guard
+- `src/exguard/exguard.module.ts` - The module
+
+## Manual Setup
+
+### 1. Create Guard File
+
+`src/exguard/exguard.guard.ts`:
 
 ```typescript
 import { Injectable, CanActivate, ExecutionContext, UnauthorizedException, ForbiddenException, Inject, Optional } from '@nestjs/common';
@@ -37,26 +49,16 @@ export class ExGuardPermissionGuard implements CanActivate {
     if (!this.exGuard) return true;
 
     const authResult = await this.exGuard.authenticate({ token, request });
-
     if (!authResult.allowed) throw new ForbiddenException(authResult.error || 'Access denied');
     if (!authResult.user) throw new ForbiddenException('User not found');
 
-    const handler = context.getHandler();
-    const permMeta = this.reflector.get(EXGUARD_PERMISSIONS_KEY, handler);
-
+    const permMeta = this.reflector.get(EXGUARD_PERMISSIONS_KEY, context.getHandler());
     if (permMeta) {
-      const { permissions, requireAll } = permMeta;
       const userPermissions = authResult.user.modules?.flatMap(m => m.permissions) || [];
-
-      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');
-        }
-      }
+      const hasPermission = permMeta.requireAll
+        ? permMeta.permissions.every(p => userPermissions.includes(p))
+        : permMeta.permissions.some(p => userPermissions.includes(p));
+      if (!hasPermission) throw new ForbiddenException('Insufficient permissions');
     }
 
     request.user = authResult.user;
@@ -65,18 +67,21 @@ export class ExGuardPermissionGuard implements CanActivate {
 
   private extractToken(request: any): string | null {
     const auth = request.headers?.authorization;
-    return auth?.startsWith('Bearer ') ? auth.substring(7) : request.headers?.['x-access-token'] || null;
+    return auth?.startsWith('Bearer ') ? auth.substring(7) : null;
   }
 }
 
-export function RequirePermissions(permissions: string[], requireAll = false) {
-  return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+export function RequirePermissions(permissions: string[], requireAll = false): any {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
     Reflect.defineMetadata(EXGUARD_PERMISSIONS_KEY, { permissions, requireAll }, descriptor.value);
+    return descriptor;
   };
 }
 ```
 
-Create `src/exguard/exguard.module.ts`:
+### 2. Create Module File
+
+`src/exguard/exguard.module.ts`:
 
 ```typescript
 import { Module, Global, DynamicModule } from '@nestjs/common';
@@ -91,19 +96,16 @@ export class ExGuardModule {
       apiKey: options.apiKey,
       cache: options.cache || { enabled: true, ttl: 300000 },
     });
-
     return {
       module: ExGuardModule,
-      providers: [
-        { provide: 'EXGUARD_INSTANCE', useValue: exGuard },
-      ],
+      providers: [{ provide: 'EXGUARD_INSTANCE', useValue: exGuard }],
       exports: ['EXGUARD_INSTANCE'],
     };
   }
 }
 ```
 
-### 2. Configure AppModule
+### 3. Configure AppModule
 
 ```typescript
 import { Module } from '@nestjs/common';
@@ -114,14 +116,13 @@ import { ExGuardModule } from './exguard/exguard.module';
     ExGuardModule.forRoot({
       baseUrl: 'https://api.exguard.com',
       apiKey: process.env.EXGUARD_API_KEY,
-      cache: { enabled: true, ttl: 300000 },
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### 3. Use in Controllers
+### 4. Use in Controllers
 
 ```typescript
 import { Controller, Get, Post, UseGuards } from '@nestjs/common';
@@ -131,6 +132,7 @@ import { ExGuardPermissionGuard, RequirePermissions } from '@/exguard/exguard.gu
 @UseGuards(ExGuardPermissionGuard)
 export class ItemsController {
   
+  // User needs ANY of these permissions
   @Get()
   @RequirePermissions(['item:read'])
   findAll() { }
@@ -139,17 +141,21 @@ export class ItemsController {
   @RequirePermissions(['item:create'])
   create() { }
 
-  @Get('drafts')
-  @RequirePermissions(['item:read_draft', 'item:admin']) // ANY of these
-  findDrafts() { }
-
+  // Multiple permissions - needs ALL
   @Delete(':id')
-  @RequirePermissions(['item:delete', 'admin'], true) // ALL of these
+  @RequirePermissions(['item:delete', 'admin'], true)
   delete() { }
 }
 ```
 
-## Token Format
+## API Reference
+
+| Decorator | Description |
+|-----------|-------------|
+| `@RequirePermissions(['perm1'])` | User needs ANY of the permissions |
+| `@RequirePermissions(['perm1', 'perm2'], true)` | User needs ALL permissions |
+
+## Token
 
 The guard extracts token from:
 - `Authorization: Bearer <token>` header
@@ -162,7 +168,7 @@ The guard extracts token from:
 | 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) |
+| cache.ttl | number | 300000 | Cache TTL (5 min) |
 
 ## Express/Fastify (Non-NestJS)
 
@@ -174,7 +180,6 @@ const guard = createExGuardExpress({
   apiKey: process.env.EXGUARD_API_KEY,
 });
 
-// Use as middleware
 app.use('/api', guard.requirePermissions(['item:read']));
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exguard-backend",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -35,7 +35,7 @@
     "create-example": "node scripts/create-example.cjs"
   },
   "bin": {
-    "exguard-backend": "scripts/setup-nestjs.cjs"
+    "exguard-backend": "scripts/setup.cjs"
   },
   "keywords": [
     "exguard",

package/scripts/setup.cjs

@@ -0,0 +1,213 @@
+/**
+ * ExGuard NestJS Auto-Setup
+ * Run: npx exguard-backend setup
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EXGUARD_GUARD_CONTENT = `import { Injectable, CanActivate, ExecutionContext, UnauthorizedException, ForbiddenException, Inject, Optional } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ExGuardBackend } from 'exguard-backend';
+
+export const EXGUARD_PERMISSIONS_KEY = 'exguard_permissions';
+export const EXGUARD_ROLES_KEY = 'exguard_roles';
+
+@Injectable()
+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);
+
+    if (!token) {
+      throw new UnauthorizedException('No token provided');
+    }
+
+    if (!this.exGuard) {
+      return true;
+    }
+
+    const authResult = await this.exGuard.authenticate({ token, request });
+
+    if (!authResult.allowed) {
+      throw new ForbiddenException(authResult.error || 'Access denied');
+    }
+
+    if (!authResult.user) {
+      throw new ForbiddenException('User not found');
+    }
+
+    const handler = context.getHandler();
+
+    const permMeta = this.reflector.get<{ permissions: string[]; requireAll?: boolean }>(
+      EXGUARD_PERMISSIONS_KEY,
+      handler,
+    );
+
+    if (permMeta) {
+      const { permissions, requireAll } = permMeta;
+      const userPermissions = authResult.user.modules?.flatMap((m: any) => m.permissions) || [];
+
+      if (requireAll) {
+        if (!permissions.every((p: string) => userPermissions.includes(p))) {
+          throw new ForbiddenException('Insufficient permissions');
+        }
+      } else {
+        if (!permissions.some((p: string) => userPermissions.includes(p))) {
+          throw new ForbiddenException('Insufficient permissions');
+        }
+      }
+    }
+
+    const roleMeta = this.reflector.get<{ roles: string[]; requireAll?: boolean }>(
+      EXGUARD_ROLES_KEY,
+      handler,
+    );
+
+    if (roleMeta) {
+      const { roles, requireAll } = roleMeta;
+      const userRoles = authResult.user.roles || [];
+
+      if (requireAll) {
+        if (!roles.every((r: string) => userRoles.includes(r))) {
+          throw new ForbiddenException('Insufficient roles');
+        }
+      } else {
+        if (!roles.some((r: string) => userRoles.includes(r))) {
+          throw new ForbiddenException('Insufficient roles');
+        }
+      }
+    }
+
+    request.user = authResult.user;
+    return true;
+  }
+
+  private extractToken(request: any): string | null {
+    const auth = request.headers?.authorization;
+    if (auth?.startsWith('Bearer ')) {
+      return auth.substring(7);
+    }
+    return request.headers?.['x-access-token'] || null;
+  }
+}
+
+export function RequirePermissions(permissions: string[], requireAll = false): any {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    Reflect.defineMetadata(EXGUARD_PERMISSIONS_KEY, { permissions, requireAll }, descriptor.value);
+    return descriptor;
+  };
+}
+
+export function RequireRoles(roles: string[], requireAll = false): any {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    Reflect.defineMetadata(EXGUARD_ROLES_KEY, { roles, requireAll }, descriptor.value);
+    return descriptor;
+  };
+}
+`;
+
+const EXGUARD_MODULE_CONTENT = `import { Module, Global, DynamicModule } from '@nestjs/common';
+import { ExGuardBackend } from 'exguard-backend';
+
+export interface ExGuardModuleOptions {
+  baseUrl: string;
+  apiKey: string;
+  cache?: {
+    enabled?: boolean;
+    ttl?: number;
+  };
+}
+
+@Global()
+@Module({})
+export class ExGuardModule {
+  static forRoot(options: ExGuardModuleOptions): DynamicModule {
+    const exGuard = new ExGuardBackend({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      cache: options.cache || { enabled: true, ttl: 300000 },
+    });
+
+    return {
+      module: ExGuardModule,
+      providers: [
+        {
+          provide: 'EXGUARD_INSTANCE',
+          useValue: exGuard,
+        },
+      ],
+      exports: ['EXGUARD_INSTANCE'],
+    };
+  }
+}
+`;
+
+function ensureDir(dirPath: string) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function writeFile(filePath: string, content: string) {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  fs.writeFileSync(filePath, content);
+  console.log(\`Created: \${filePath}\`);
+}
+
+function setupNestJS() {
+  const srcDir = path.join(process.cwd(), 'src');
+  const exguardDir = path.join(srcDir, 'exguard');
+
+  if (!fs.existsSync(srcDir)) {
+    console.error('Error: Run this command in your NestJS project root (where src/ exists)');
+    process.exit(1);
+  }
+
+  ensureDir(exguardDir);
+
+  writeFile(path.join(exguardDir, 'exguard.guard.ts'), EXGUARD_GUARD_CONTENT);
+  writeFile(path.join(exguardDir, 'exguard.module.ts'), EXGUARD_MODULE_CONTENT);
+
+  console.log('\\n✅ ExGuard setup complete!');
+  console.log('\\nNext steps:');
+  console.log('1. Add to app.module.ts:');
+  console.log('   import { ExGuardModule } from "./exguard/exguard.module";');
+  console.log('   ');
+  console.log('   @Module({');
+  console.log('     imports: [');
+  console.log('       ExGuardModule.forRoot({');
+  console.log('         baseUrl: "https://api.exguard.com",');
+  console.log('         apiKey: process.env.EXGUARD_API_KEY,');
+  console.log('       }),');
+  console.log('     ],');
+  console.log('   })');
+  console.log('   export class AppModule {}');
+  console.log('\\n2. Use in controllers:');
+  console.log('   import { ExGuardPermissionGuard, RequirePermissions } from "@/exguard/exguard.guard";');
+  console.log('   ');
+  console.log('   @Controller("items")');
+  console.log('   @UseGuards(ExGuardPermissionGuard)');
+  console.log('   export class ItemsController {');
+  console.log('     @Get() @RequirePermissions(["item:read"]) findAll() {}');
+  console.log('     @Post() @RequirePermissions(["item:create"]) create() {}');
+  console.log('   }');
+}
+
+const args = process.argv.slice(2);
+if (args[0] === 'setup') {
+  setupNestJS();
+} else {
+  console.log('ExGuard NestJS Setup');
+  console.log('Usage: npx exguard-backend setup');
+  console.log('');
+  console.log('This will create:');
+  console.log('  - src/exguard/exguard.guard.ts');
+  console.log('  - src/exguard/exguard.module.ts');
+}