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

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:

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

Logger Usage

Basic Usage

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

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

// 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

import { Logger } from 'be-core';

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

Environment-Specific Configuration

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

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

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

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

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:

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:

// 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:

// 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:

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:

// 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

nx test core

Linting

nx lint core