@biggora/claude-plugins 1.2.2 → 1.3.0

package/src/skills/nest-best-practices/references/security-authorization.md

@@ -0,0 +1,196 @@
+---
+name: authorization
+description: Role-based access control (RBAC) and CASL integration
+---
+
+# Authorization
+
+Authorization determines what authenticated users can do. NestJS supports RBAC, claims-based, and policy-based authorization.
+
+## Basic RBAC Implementation
+
+### 1. Define Roles
+
+```typescript
+// role.enum.ts
+export enum Role {
+  User = 'user',
+  Admin = 'admin',
+}
+```
+
+### 2. Create Roles Decorator
+
+```typescript
+// roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+import { Role } from './role.enum';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
+```
+
+### 3. Create Roles Guard
+
+```typescript
+// roles.guard.ts
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from './role.enum';
+import { ROLES_KEY } from './roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    
+    if (!requiredRoles) return true;
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+}
+```
+
+### 4. Apply to Routes
+
+```typescript
+@Post()
+@Roles(Role.Admin)
+@UseGuards(AuthGuard, RolesGuard)
+create(@Body() dto: CreateDto) {
+  return this.service.create(dto);
+}
+```
+
+### 5. Register Globally
+
+```typescript
+@Module({
+  providers: [
+    { provide: APP_GUARD, useClass: RolesGuard },
+  ],
+})
+export class AppModule {}
+```
+
+## Claims-Based Authorization
+
+Check specific permissions instead of roles:
+
+```typescript
+// permissions.decorator.ts
+export const PERMISSIONS_KEY = 'permissions';
+export const RequirePermissions = (...permissions: Permission[]) =>
+  SetMetadata(PERMISSIONS_KEY, permissions);
+
+// Usage
+@Post()
+@RequirePermissions(Permission.CREATE_POST)
+create() {}
+```
+
+## CASL Integration
+
+For complex authorization rules:
+
+```bash
+npm install @casl/ability
+```
+
+### Define Abilities
+
+```typescript
+// casl-ability.factory.ts
+import { AbilityBuilder, createMongoAbility, MongoAbility } from '@casl/ability';
+
+export type AppAbility = MongoAbility<[Action, Subjects]>;
+
+@Injectable()
+export class CaslAbilityFactory {
+  createForUser(user: User) {
+    const { can, cannot, build } = new AbilityBuilder(createMongoAbility);
+
+    if (user.isAdmin) {
+      can(Action.Manage, 'all');
+    } else {
+      can(Action.Read, 'all');
+      can(Action.Update, Article, { authorId: user.id });
+      cannot(Action.Delete, Article, { isPublished: true });
+    }
+
+    return build();
+  }
+}
+```
+
+### Use in Services
+
+```typescript
+@Injectable()
+export class ArticlesService {
+  constructor(private caslAbilityFactory: CaslAbilityFactory) {}
+
+  async update(user: User, articleId: string, dto: UpdateDto) {
+    const article = await this.findOne(articleId);
+    const ability = this.caslAbilityFactory.createForUser(user);
+
+    if (!ability.can(Action.Update, article)) {
+      throw new ForbiddenException('Cannot update this article');
+    }
+
+    return this.articlesRepository.update(articleId, dto);
+  }
+}
+```
+
+### Policies Guard
+
+```typescript
+@Injectable()
+export class PoliciesGuard implements CanActivate {
+  constructor(
+    private reflector: Reflector,
+    private caslAbilityFactory: CaslAbilityFactory,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const policyHandlers = this.reflector.get<PolicyHandler[]>(
+      CHECK_POLICIES_KEY,
+      context.getHandler(),
+    ) || [];
+
+    const { user } = context.switchToHttp().getRequest();
+    const ability = this.caslAbilityFactory.createForUser(user);
+
+    return policyHandlers.every((handler) =>
+      typeof handler === 'function'
+        ? handler(ability)
+        : handler.handle(ability),
+    );
+  }
+}
+
+// Usage
+@Get()
+@UseGuards(PoliciesGuard)
+@CheckPolicies((ability: AppAbility) => ability.can(Action.Read, Article))
+findAll() {}
+```
+
+## Key Points
+
+- Authorization is independent from authentication
+- Use `Reflector` to access route metadata
+- CASL provides fine-grained, attribute-based control
+- `user.roles` should be attached by authentication guard
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/authorization
+-->

package/src/skills/nest-best-practices/references/security-cors-helmet-rate-limiting.md

@@ -0,0 +1,204 @@
+---
+name: cors-helmet-rate-limiting
+description: CORS, security headers, and rate limiting protection
+---
+
+# Security Middleware
+
+Essential security measures for NestJS applications.
+
+## CORS (Cross-Origin Resource Sharing)
+
+Enable CORS to allow cross-origin requests:
+
+```typescript
+// Simple enable
+const app = await NestFactory.create(AppModule, { cors: true });
+
+// Or with configuration
+const app = await NestFactory.create(AppModule);
+app.enableCors({
+  origin: ['https://example.com', 'https://app.example.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  credentials: true,
+});
+```
+
+Dynamic origin:
+
+```typescript
+app.enableCors({
+  origin: (origin, callback) => {
+    const whitelist = ['https://example.com'];
+    if (!origin || whitelist.includes(origin)) {
+      callback(null, true);
+    } else {
+      callback(new Error('Not allowed by CORS'));
+    }
+  },
+});
+```
+
+## Helmet (Security Headers)
+
+```bash
+npm install helmet
+```
+
+```typescript
+import helmet from 'helmet';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.use(helmet());
+  await app.listen(3000);
+}
+```
+
+## Rate Limiting
+
+Protect against brute-force attacks:
+
+```bash
+npm install @nestjs/throttler
+```
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { APP_GUARD } from '@nestjs/core';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      throttlers: [
+        { ttl: 60000, limit: 10 }, // 10 requests per minute
+      ],
+    }),
+  ],
+  providers: [
+    { provide: APP_GUARD, useClass: ThrottlerGuard },
+  ],
+})
+export class AppModule {}
+```
+
+### Multiple Limits
+
+```typescript
+ThrottlerModule.forRoot({
+  throttlers: [
+    { name: 'short', ttl: 1000, limit: 3 },    // 3 per second
+    { name: 'medium', ttl: 10000, limit: 20 }, // 20 per 10 seconds
+    { name: 'long', ttl: 60000, limit: 100 },  // 100 per minute
+  ],
+});
+```
+
+### Skip Routes
+
+```typescript
+import { SkipThrottle } from '@nestjs/throttler';
+
+@SkipThrottle()
+@Controller('health')
+export class HealthController {}
+
+// Or skip specific throttlers
+@SkipThrottle({ short: true })
+@Get()
+findAll() {}
+```
+
+### Override Limits
+
+```typescript
+import { Throttle } from '@nestjs/throttler';
+
+@Throttle({ default: { limit: 3, ttl: 60000 } })
+@Get()
+findAll() {}
+```
+
+### Behind Proxy
+
+```typescript
+// main.ts
+const app = await NestFactory.create<NestExpressApplication>(AppModule);
+app.set('trust proxy', 'loopback');
+
+// Custom tracker for proxy
+@Injectable()
+export class ThrottlerBehindProxyGuard extends ThrottlerGuard {
+  protected async getTracker(req: Record<string, any>): Promise<string> {
+    return req.ips.length ? req.ips[0] : req.ip;
+  }
+}
+```
+
+### Redis Storage
+
+For distributed systems:
+
+```bash
+npm install @nest-lab/throttler-storage-redis
+```
+
+```typescript
+import { ThrottlerStorageRedisService } from '@nest-lab/throttler-storage-redis';
+
+ThrottlerModule.forRoot({
+  throttlers: [{ ttl: 60000, limit: 10 }],
+  storage: new ThrottlerStorageRedisService('redis://localhost:6379'),
+});
+```
+
+### WebSocket Rate Limiting
+
+```typescript
+@Injectable()
+export class WsThrottlerGuard extends ThrottlerGuard {
+  async handleRequest(requestProps: ThrottlerRequest): Promise<boolean> {
+    const { context, limit, ttl } = requestProps;
+    const client = context.switchToWs().getClient();
+    const tracker = client._socket.remoteAddress;
+    // Custom logic
+    return true;
+  }
+}
+```
+
+### GraphQL Rate Limiting
+
+```typescript
+@Injectable()
+export class GqlThrottlerGuard extends ThrottlerGuard {
+  getRequestResponse(context: ExecutionContext) {
+    const gqlCtx = GqlExecutionContext.create(context);
+    const ctx = gqlCtx.getContext();
+    return { req: ctx.req, res: ctx.res };
+  }
+}
+```
+
+## Time Helpers
+
+```typescript
+import { seconds, minutes, hours } from '@nestjs/throttler';
+
+ThrottlerModule.forRoot({
+  throttlers: [
+    { ttl: seconds(30), limit: 10 },
+    { ttl: minutes(5), limit: 100 },
+  ],
+});
+```
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/cors
+- https://docs.nestjs.com/security/helmet
+- https://docs.nestjs.com/security/rate-limiting
+-->

package/src/skills/nest-best-practices/references/security-encryption-hashing.md

@@ -0,0 +1,93 @@
+---
+name: encryption-hashing
+description: Encryption and password hashing (bcrypt, argon2) for NestJS
+---
+
+# Encryption and Hashing
+
+Nest uses Node.js built-in `crypto` for encryption. For password hashing, use bcrypt or argon2.
+
+## Encryption (crypto)
+
+```typescript
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from 'node:crypto';
+import { promisify } from 'node:util';
+
+const iv = randomBytes(16);
+const key = (await promisify(scrypt)(password, 'salt', 32)) as Buffer;
+
+// Encrypt
+const cipher = createCipheriv('aes-256-ctr', key, iv);
+const encrypted = Buffer.concat([
+  cipher.update(textToEncrypt),
+  cipher.final(),
+]);
+
+// Decrypt
+const decipher = createDecipheriv('aes-256-ctr', key, iv);
+const decrypted = Buffer.concat([
+  decipher.update(encrypted),
+  decipher.final(),
+]);
+```
+
+## Hashing (bcrypt)
+
+```bash
+npm i bcrypt
+npm i -D @types/bcrypt
+```
+
+```typescript
+import * as bcrypt from 'bcrypt';
+
+// Hash password
+const saltOrRounds = 10;
+const hash = await bcrypt.hash(password, saltOrRounds);
+
+// Generate salt
+const salt = await bcrypt.genSalt();
+
+// Verify
+const isMatch = await bcrypt.compare(password, hash);
+```
+
+## Hashing (argon2)
+
+```bash
+npm i argon2
+```
+
+```typescript
+import * as argon2 from 'argon2';
+
+const hash = await argon2.hash(password);
+const isMatch = await argon2.verify(hash, password);
+```
+
+## Injectable Hashing Service
+
+```typescript
+@Injectable()
+export class HashingService {
+  async hash(password: string): Promise<string> {
+    return bcrypt.hash(password, 10);
+  }
+
+  async compare(password: string, hash: string): Promise<boolean> {
+    return bcrypt.compare(password, hash);
+  }
+}
+```
+
+## Key Points
+
+- Use bcrypt or argon2 for passwords (argon2 preferred for new apps)
+- Node.js `crypto` for encryption/decryption
+- Never store plain passwords
+- Use strong salts; bcrypt handles salt internally
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/encryption-and-hashing
+-->

package/src/skills/nest-best-practices/references/techniques-caching.md

@@ -0,0 +1,142 @@
+---
+name: caching
+description: Caching with @nestjs/cache-manager and Redis integration
+---
+
+# Caching
+
+Caching improves performance by storing frequently accessed data for quick retrieval.
+
+## Installation
+
+```bash
+npm install @nestjs/cache-manager cache-manager
+```
+
+## Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CacheModule } from '@nestjs/cache-manager';
+
+@Module({
+  imports: [CacheModule.register()],
+})
+export class AppModule {}
+```
+
+## Interacting with Cache
+
+Inject the cache manager:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { CACHE_MANAGER, Cache } from '@nestjs/cache-manager';
+
+@Injectable()
+export class CatsService {
+  constructor(@Inject(CACHE_MANAGER) private cacheManager: Cache) {}
+
+  async getCats() {
+    // Get from cache
+    const cached = await this.cacheManager.get('cats');
+    if (cached) return cached;
+
+    const cats = await this.fetchCats();
+    
+    // Set with TTL (milliseconds)
+    await this.cacheManager.set('cats', cats, 60000);
+    return cats;
+  }
+
+  async clearCache() {
+    await this.cacheManager.del('cats');
+    // Or clear all
+    await this.cacheManager.clear();
+  }
+}
+```
+
+## Auto-caching Responses
+
+Use `CacheInterceptor` for automatic GET endpoint caching:
+
+```typescript
+import { Controller, Get, UseInterceptors } from '@nestjs/common';
+import { CacheInterceptor, CacheKey, CacheTTL } from '@nestjs/cache-manager';
+
+@Controller('cats')
+@UseInterceptors(CacheInterceptor)
+export class CatsController {
+  @Get()
+  @CacheKey('all-cats')
+  @CacheTTL(30000)
+  findAll() {
+    return this.catsService.findAll();
+  }
+}
+```
+
+Global cache interceptor:
+
+```typescript
+@Module({
+  providers: [
+    { provide: APP_INTERCEPTOR, useClass: CacheInterceptor },
+  ],
+})
+export class AppModule {}
+```
+
+## Configuration
+
+```typescript
+CacheModule.register({
+  ttl: 5000,        // Default TTL in milliseconds
+  isGlobal: true,   // Available everywhere without importing
+});
+```
+
+## Redis Integration
+
+Install Redis adapter:
+
+```bash
+npm install @keyv/redis
+```
+
+Configure multiple stores:
+
+```typescript
+import { CacheModule } from '@nestjs/cache-manager';
+import KeyvRedis from '@keyv/redis';
+import { Keyv } from 'keyv';
+import { CacheableMemory } from 'cacheable';
+
+@Module({
+  imports: [
+    CacheModule.registerAsync({
+      useFactory: async () => ({
+        stores: [
+          new Keyv({ store: new CacheableMemory({ ttl: 60000 }) }),
+          new KeyvRedis('redis://localhost:6379'),
+        ],
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Key Points
+
+- Only GET endpoints are auto-cached
+- `CacheInterceptor` doesn't work with GraphQL field resolvers
+- Use `@CacheKey()` for custom cache keys
+- Set `ttl: 0` for no expiration
+- Works with WebSockets and Microservices
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/caching
+-->