Easy Security Library

A comprehensive security library for NestJS applications providing authentication, authorization, rate limiting, and AWS integration.

🎯 Core Philosophy

This library focuses on business logic and core security services rather than presentation layer concerns. Controllers are provided as examples only - implement your own controllers to match your application's API design.

🚀 Quick Start

Installation

npm install @454creative/easy-security

Basic Setup

import { EasySecurityModule } from '@454creative/easy-security';

@Module({
  imports: [
    EasySecurityModule.forRoot({
      // AWS Cognito configuration
      cognito: {
        userPoolId: process.env.AWS_COGNITO_USER_POOL_ID,
        clientId: process.env.AWS_COGNITO_CLIENT_ID,
        region: process.env.AWS_REGION,
      },
      
      // JWT configuration
      jwt: {
        secret: process.env.JWT_SECRET,
        expiresIn: '1d',
        issuer: process.env.JWT_ISSUER,
        audience: process.env.JWT_AUDIENCE,
      },
    }),
  ],
})
export class AppModule {}

🔧 Core Services

Authentication Services

import { CognitoService, AuthService } from '@454creative/easy-security';

@Injectable()
export class MyAuthService {
  constructor(
    private cognitoService: CognitoService,
    private authService: AuthService,
  ) {}

  async login(credentials: AuthLoginDto) {
    return this.cognitoService.authenticateUser(credentials);
  }

  async register(userData: AuthRegisterDto) {
    return this.cognitoService.registerUser(userData);
  }
}

Authorization Services

import { PermissionService } from '@454creative/easy-security';

@Injectable()
export class MyAuthorizationService {
  constructor(private permissionService: PermissionService) {}

  async checkAccess(userRoles: string[], requiredPermissions: string[]) {
    return this.permissionService.hasRequiredPermissions(userRoles, requiredPermissions);
  }
}

Rate Limiting

import { RateLimiterService } from '@454creative/easy-security';

@Injectable()
export class MyRateLimitService {
  constructor(private rateLimiterService: RateLimiterService) {}

  async checkRateLimit(userId: string, action: string) {
    return this.rateLimiterService.checkRateLimit(userId, action);
  }
}

🛡️ Guards & Decorators

Guards

import { AuthGuard, RolesGuard, RateLimiterGuard } from '@454creative/easy-security';

@Controller('api')
export class MyController {
  @Get('protected')
  @UseGuards(AuthGuard)
  getProtectedData() {
    return { message: 'Protected data' };
  }

  @Get('admin')
  @UseGuards(RolesGuard)
  @Roles('ADMIN')
  getAdminData() {
    return { message: 'Admin data' };
  }

  @Post('api-call')
  @UseGuards(RateLimiterGuard)
  @RateLimit(100, 60000) // 100 requests per minute
  makeApiCall() {
    return { message: 'API call' };
  }
}

Decorators

import { Roles, Permissions, RateLimit } from '@454creative/easy-security';

@Controller('users')
export class UserController {
  @Get()
  @Roles('ADMIN', 'USER')
  @Permissions('READ_USERS')
  getUsers() {
    // Implementation
  }

  @Post()
  @Roles('ADMIN')
  @Permissions('CREATE_USERS')
  @RateLimit(10, 60000) // 10 requests per minute
  createUser() {
    // Implementation
  }
}

🔐 Authentication Strategies

The library supports multiple authentication strategies:

• JWT Strategy - Standard JWT token authentication
• Lambda Strategy - AWS Lambda function authentication
• AWS SigV4 Strategy - AWS signature authentication
• Task Role Strategy - AWS ECS task role authentication
• Auto Strategy - Automatically selects the best strategy

import { JwtStrategy, AutoStrategy } from '@454creative/easy-security';

// Use specific strategy
@UseGuards(AuthGuard('jwt'))
getData() { }

// Use auto strategy (recommended)
@UseGuards(AuthGuard('auto'))
getData() { }

📝 Implementing Your Own Controllers

Basic Authentication Controller

import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { CognitoService, AuthGuard } from '@454creative/easy-security';

@Controller('auth')
export class AuthController {
  constructor(private cognitoService: CognitoService) {}

  @Post('login')
  async login(@Body() credentials: AuthLoginDto) {
    return this.cognitoService.authenticateUser(credentials);
  }

  @Post('register')
  async register(@Body() userData: AuthRegisterDto) {
    return this.cognitoService.registerUser(userData);
  }

  @Get('profile')
  @UseGuards(AuthGuard)
  async getProfile(@Request() req) {
    return req.user;
  }
}

Advanced Token Management Controller

import { Controller, Post, Param, UseGuards } from '@nestjs/common';
import { CognitoService, AuthGuard } from '@454creative/easy-security';

@Controller('token-management')
@UseGuards(AuthGuard)
export class TokenManagementController {
  constructor(private cognitoService: CognitoService) {}

  @Post('revoke-user-tokens/:username')
  async revokeUserTokens(@Param('username') username: string) {
    return this.cognitoService.revokeUserTokens(username);
  }

  @Post('revoke-refresh-token')
  async revokeRefreshToken(@Body() body: { refreshToken: string }) {
    return this.cognitoService.revokeRefreshToken(body.refreshToken);
  }
}

📚 Examples

The library includes example controllers in the examples/ folder:

• AuthController - Basic authentication endpoints
• TokenManagementController - Advanced token management
• AuthTestController - Testing endpoints

These are for reference only - implement your own controllers to match your application's needs.

🔧 Configuration

Full Configuration Example

const securityConfig: EasySecurityConfig = {
  // AWS Cognito
  cognito: {
    userPoolId: process.env.AWS_COGNITO_USER_POOL_ID,
    clientId: process.env.AWS_COGNITO_CLIENT_ID,
    region: process.env.AWS_REGION,
    authority: process.env.AWS_COGNITO_AUTHORITY,
  },

  // JWT Configuration
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: '1d',
    issuer: process.env.JWT_ISSUER,
    audience: process.env.JWT_AUDIENCE,
    algorithms: ['RS256'],
  },

  // Rate Limiting
  rateLimiting: {
    enabled: true,
    redis: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT),
      password: process.env.REDIS_PASSWORD,
    },
  },

  // Feature Flags
  features: {
    authentication: true,
    authorization: true,
    rateLimiting: true,
    auditLogging: true,
  },

  // RBAC Configuration
  rbac: {
    adminRole: 'ADMIN',
    defaultRole: 'USER',
    roles: ['ADMIN', 'USER', 'READONLY'],
  },
};

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- --testPathPattern=auth.service.spec.ts

📦 Exports

Core Services

• CognitoService - AWS Cognito integration
• AuthService - JWT token management
• PermissionService - Role-based access control
• RateLimiterService - Rate limiting functionality
• FeatureFlagService - Feature flag management

Guards

• AuthGuard - Authentication guard
• RolesGuard - Role-based authorization guard
• RateLimiterGuard - Rate limiting guard

Decorators

• @Roles() - Role-based access control
• @Permissions() - Permission-based access control
• @RateLimit() - Rate limiting configuration

Strategies

• JwtStrategy - JWT authentication
• LambdaStrategy - AWS Lambda authentication
• AwsSigV4Strategy - AWS signature authentication
• TaskRoleStrategy - AWS task role authentication
• AutoStrategy - Automatic strategy selection

Utilities

• AuthUtils - Authentication utilities
• ROLES - Role constants
• PERMISSIONS - Permission constants

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.