# be-core

Core Express backend package with middleware, logging, security, and base application setup for building production-ready TypeScript applications.

## Features

- **BaseApp**: Pre-configured Express application with production-ready defaults
- **Middleware**: Security, CORS, rate limiting, compression, and error handling
- **Logging**: Structured logging with Winston and daily rotation
- **Security**: Helmet, HPP, and enhanced security plugins
- **HTTP Utilities**: Status codes, API response formatting
- **Plugin System**: Extensible plugin architecture

## Installation

```bash
npm install be-core
```

- **TypeScript**: Full TypeScript support with proper type definitions

## Installation

This package is part of the monorepo and should be used as an internal dependency:

```json
{
  "dependencies": {
    "be-core": "workspace:*"
  }
}
```

## Logger Usage

### Basic Usage

```typescript
import { defaultLogger, createLogger } from 'be-core';

// Use the default logger
defaultLogger.info('Application started');
defaultLogger.error('Something went wrong', { error: 'details' });

// Create a custom logger
const logger = createLogger({
  level: 'debug',
  dir: './logs',
  format: 'json',
});

logger.info('Custom logger message');
```

### Configuration Options

```typescript
interface LoggingConfig {
  level?: string; // Log level (default: 'info')
  dir?: string; // Directory for log files (default: './logs')
  format?: 'json' | 'simple'; // Log format (default: 'simple')
  httpLogging?: boolean; // Enable HTTP logging (default: true)
  maxFiles?: number; // Max files to keep (default: 30)
  correlationId?: boolean; // Add correlation IDs (default: true)
}
```

### Logging Methods

```typescript
// Available logging methods
logger.info('Information message', { userId: 123 });
logger.warn('Warning message', { deprecated: true });
logger.error('Error message', { error: 'details' });
logger.debug('Debug message', { step: 'validation' });

// Error objects are handled specially
try {
  throw new Error('Something failed');
} catch (error) {
  logger.error(error, { context: 'user-registration' });
}
```

### Static Create Method

```typescript
import { Logger } from 'be-core';

const logger = Logger.create({
  level: 'debug',
  dir: './custom-logs',
  format: 'json',
});
```

### Environment-Specific Configuration

```typescript
import { createLogger } from 'be-core';

const logger = createLogger({
  level: process.env.LOG_LEVEL || 'info',
  dir: process.env.LOG_DIR || './logs',
  format: process.env.NODE_ENV === 'production' ? 'json' : 'simple',
});
```

### Log Files

The logger creates the following log files with daily rotation:

- `combined/YYYY-MM-DD.log` - All log levels
- `error/YYYY-MM-DD.log` - Error logs only

Files are automatically rotated daily and compressed (zipped) for storage efficiency.

### Available Log Levels

- `error` - Error messages
- `warn` - Warning messages
- `info` - Informational messages
- `debug` - Debug messages
- `verbose` - Verbose messages

### Integration with Express

```typescript
import express from 'express';
import { createLogger } from 'be-core';

const app = express();
const logger = createLogger({ serviceName: 'api-server' });

app.use((req, res, next) => {
  logger.info('Request received', {
    method: req.method,
    url: req.url,
    ip: req.ip,
  });
  next();
});

app.listen(3000, () => {
  logger.info('Server started on port 3000');
});
```

## Validation Integration

The `be-core` package includes integrated validation and security middleware powered by `be-validation`. This provides automatic protection against common security threats and comprehensive input validation for all applications using BaseApp.

### Automatic Security Features

When you extend `BaseApp`, the following security features are automatically enabled:

- **XSS Protection**: Prevents cross-site scripting attacks
- **SQL Injection Protection**: Blocks SQL injection attempts
- **Request Sanitization**: Cleanses all incoming data (body, query, params)
- **Security Headers**: Sets appropriate security headers (CSP, X-Frame-Options, etc.)
- **Content Security Policy**: Configurable CSP directives

### Basic Usage

```typescript
import { BaseApp } from 'be-core';

// Validation is automatically enabled when extending BaseApp
export class App extends BaseApp {
  constructor() {
    super({
      // Validation configuration is optional - uses secure defaults
      validation: {
        enabled: true, // Default: true
        enableXSSProtection: true,
        enableSQLInjectionProtection: true,
        // ... other options
      },
    });
  }
}

// That's it! Your app now has comprehensive validation and security
const app = new App();
app.start();
```

### Validation Configuration

```typescript
interface ValidationConfig {
  enabled?: boolean; // Enable/disable validation plugin (default: true)
  enableXSSProtection?: boolean; // XSS protection (default: true)
  enableSQLInjectionProtection?: boolean; // SQL injection protection (default: true)
  globalValidation?: {
    enabled: boolean;
    soft: boolean; // Soft validation vs strict validation
    options: object; // Joi/Zod validation options
  };
  globalSanitization?: {
    body?: SanitizationOptions;
    query?: SanitizationOptions;
    params?: SanitizationOptions;
  };
  csp?: {
    enabled: boolean;
    directives: Record<string, string[]>; // CSP directives
  };
  customValidators?: Record<string, ValidatorFunction>;
  errorHandler?: ValidationErrorHandler;
}
```

### Advanced Configuration

```typescript
import { BaseApp } from 'be-core';

export class App extends BaseApp {
  constructor() {
    super({
      validation: {
        // Custom CSP configuration
        csp: {
          enabled: true,
          directives: {
            'default-src': ["'self'"],
            'script-src': ["'self'", "'unsafe-inline'"],
            'style-src': ["'self'", "'unsafe-inline'"],
            'img-src': ["'self'", 'data:', 'https:'],
          },
        },
        // Custom sanitization options
        globalSanitization: {
          body: {
            html: { enabled: true, stripTags: true },
            xss: { enabled: true },
            sql: { enabled: true },
          },
          query: {
            html: { enabled: true, stripTags: true },
            xss: { enabled: true },
            sql: { enabled: true },
          },
        },
        // Custom error handling
        errorHandler: (err, req, res, next) => {
          // Custom validation error response
          res.status(400).json({
            error: 'Validation failed',
            message: 'Invalid input detected',
            timestamp: new Date().toISOString(),
          });
        },
      },
    });
  }
}
```

### Accessing Validation Plugin

You can access the validation plugin for advanced usage:

```typescript
import { BaseApp } from 'be-core';

export class App extends BaseApp {
  setupCustomValidation() {
    // Get the validation plugin instance
    const validationPlugin = this.getValidationPlugin();

    if (validationPlugin) {
      // Access validation utilities
      const sanitizer = validationPlugin.getSanitizer();
      const xssProtection = validationPlugin.getXSSProtection();
      const validationMiddleware = validationPlugin.getValidationMiddleware();

      // Use them in custom middleware or routes
      this.app.use('/api/custom', (req, res, next) => {
        // Custom validation logic
        const cleanData = sanitizer.sanitizeObject(req.body);
        req.body = cleanData;
        next();
      });
    }
  }
}
```

### Route-Level Validation

For endpoint-specific validation beyond the global middleware:

```typescript
// In your controllers or route handlers
app.post('/api/users', (req, res, next) => {
  // Request is already sanitized by global middleware
  // Add additional route-specific validation if needed

  const userData = req.body; // Already sanitized and safe
  // Process user creation...
});
```

### Health Checks

The validation system includes health checks that are automatically integrated:

```typescript
// GET /health will include validation system status
// GET /health/detailed provides comprehensive validation health info

// Health check response includes:
{
  "validation": {
    "status": "healthy",
    "checks": {
      "xssProtection": true,
      "sqlProtection": true,
      "globalValidation": true,
      "globalSanitization": true,
      "modulesLoaded": true
    },
    "message": "Validation system is fully operational"
  }
}
```

### Disabling Validation

If you need to disable validation for testing or specific environments:

```typescript
export class App extends BaseApp {
  constructor() {
    super({
      validation: {
        enabled: false, // Disables all validation middleware
      },
    });
  }
}
```

### Security Benefits

The integrated validation provides:

1. **Automatic Protection**: Zero-configuration security for common threats
2. **Performance Optimized**: Runs at middleware level with minimal overhead
3. **Comprehensive Coverage**: Protects all endpoints consistently
4. **Graceful Degradation**: Falls back to basic security headers if validation modules unavailable
5. **Customizable**: Configurable to meet specific application needs

### Migration from Manual Validation

If migrating from manual validation:

````typescript
// Before: Manual validation in each controller
app.post('/api/users', (req, res) => {
  // Manual sanitization
  const cleanEmail = sanitizeEmail(req.body.email);
  const cleanName = sanitizeName(req.body.name);
  // ... validation logic
});

// After: Automatic validation with BaseApp
export class App extends BaseApp {
  // Validation happens automatically at middleware level
  // Controllers receive clean, validated data
}

app.post('/api/users', (req, res) => {
  // req.body is already sanitized and validated
  const { email, name } = req.body;
  // ... business logic only
});

## Development

### Building

```bash
nx build core
````

### Testing

```bash
nx test core
```

### Linting

```bash
nx lint core
```