@tumbaland/backend-core 1.16.0

package/src/logging/logger.ts

@@ -0,0 +1,103 @@
+import winston from 'winston';
+import path from 'path';
+import fs from 'fs';
+
+// Define log levels
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  debug: 4,
+};
+
+const level = () => {
+  const env = process.env.NODE_ENV || 'development';
+  const isDevelopment = env === 'development';
+  return isDevelopment ? 'debug' : 'info';
+};
+
+// Define colors for each level
+const colors = {
+  error: 'red',
+  warn: 'yellow',
+  info: 'green',
+  http: 'magenta',
+  debug: 'white',
+};
+
+winston.addColors(colors);
+
+// Define format for console (human-readable)
+const consoleFormat = winston.format.combine(
+  winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:ms' }),
+  winston.format.colorize({ all: true }),
+  winston.format.printf(
+    (info: any) => `${info.timestamp} ${info.level}: ${info.message}`,
+  ),
+);
+
+// Define JSON format for production (structured logging)
+const jsonFormat = winston.format.combine(
+  winston.format.timestamp(),
+  winston.format.errors({ stack: true }),
+  winston.format.json()
+);
+
+// Choose format based on environment
+const isProduction = process.env.NODE_ENV === 'production';
+const logFormat = isProduction ? jsonFormat : consoleFormat;
+
+// Define which transports the logger must use
+const transports: winston.transport[] = [
+  // Console transport (goes to Docker stdout/stderr)
+  new winston.transports.Console({
+    format: logFormat,
+    level: level()
+  }),
+];
+
+// Add file transport only in development (optional)
+if (!isProduction && process.env.LOG_TO_FILE === 'true') {
+
+  // Create logs directory if it doesn't exist
+  const logsDir = path.join(process.cwd(), 'logs');
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+
+  transports.push(
+    new winston.transports.File({
+      filename: path.join(logsDir, 'app.log'),
+      format: jsonFormat,
+      level: 'debug'
+    })
+  );
+}
+
+// Create the logger instance
+const logger = winston.createLogger({
+  level: level(),
+  levels,
+  format: logFormat,
+  transports,
+  // Handle exceptions and rejections
+  exceptionHandlers: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    })
+  ],
+  rejectionHandlers: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    })
+  ]
+});
+
+export default logger;

package/src/metrics/index.test.ts

@@ -0,0 +1,91 @@
+import { Request, Response } from 'express';
+import {
+  activeConnections,
+  businessMetrics,
+  httpRequestDuration,
+  httpRequestsTotal,
+  metricsHandler,
+  metricsMiddleware,
+  register
+} from './index';
+
+function mockRes(): Response {
+  const res: Partial<Response> & { _finishHandler?: () => void } = {};
+  res.set = jest.fn().mockReturnValue(res);
+  res.end = jest.fn().mockReturnValue(res);
+  res.status = jest.fn().mockReturnValue(res);
+  res.statusCode = 200;
+  res.on = jest.fn((event: string, handler: () => void) => {
+    if (event === 'finish') res._finishHandler = handler;
+    return res as Response;
+  });
+  return res as Response;
+}
+
+describe('metricsHandler', () => {
+  it('writes the registry content-type header and the serialized metrics body', async () => {
+    const res = mockRes();
+
+    await metricsHandler({} as Request, res);
+
+    expect(res.set).toHaveBeenCalledWith('Content-Type', register.contentType);
+    expect(res.end).toHaveBeenCalledWith(expect.any(String));
+  });
+
+  it('responds 500 when the registry fails to serialize metrics', async () => {
+    const res = mockRes();
+    jest.spyOn(register, 'metrics').mockRejectedValueOnce(new Error('boom'));
+
+    await metricsHandler({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.end).toHaveBeenCalledWith('Error generating metrics');
+  });
+});
+
+describe('metricsMiddleware', () => {
+  it('increments active connections immediately and decrements once the response finishes', async () => {
+    const req = { method: 'GET', url: '/albums' } as Request;
+    const res = mockRes() as Response & { _finishHandler?: () => void };
+    const next = jest.fn();
+    const before = (await activeConnections.get()).values[0]?.value ?? 0;
+
+    metricsMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(res.on).toHaveBeenCalledWith('finish', expect.any(Function));
+    expect((await activeConnections.get()).values[0]?.value).toBe(before + 1);
+
+    (res as any)._finishHandler();
+
+    expect((await activeConnections.get()).values[0]?.value).toBe(before);
+  });
+
+  it('records request duration and total-count metrics labeled by method/url/status on finish', () => {
+    const req = { method: 'POST', url: '/albums' } as Request;
+    const res = mockRes();
+    res.statusCode = 201;
+    const next = jest.fn();
+
+    const durationSpy = jest.spyOn(httpRequestDuration, 'labels');
+    const totalSpy = jest.spyOn(httpRequestsTotal, 'labels');
+
+    metricsMiddleware(req, res, next);
+    (res as any)._finishHandler();
+
+    expect(durationSpy).toHaveBeenCalledWith('POST', '/albums', '201');
+    expect(totalSpy).toHaveBeenCalledWith('POST', '/albums', '201');
+
+    durationSpy.mockRestore();
+    totalSpy.mockRestore();
+  });
+});
+
+describe('businessMetrics', () => {
+  it('exposes counters that can be incremented without throwing', () => {
+    expect(() => businessMetrics.albumsCreated.inc()).not.toThrow();
+    expect(() => businessMetrics.filesUploaded.inc({ file_type: 'image' })).not.toThrow();
+    expect(() => businessMetrics.usersRegistered.inc()).not.toThrow();
+    expect(() => businessMetrics.paymentsProcessed.inc({ status: 'success', method: 'card' })).not.toThrow();
+  });
+});

package/src/metrics/index.ts

@@ -0,0 +1,110 @@
+import promClient from 'prom-client';
+
+// Create a Registry which registers the metrics
+const register = new promClient.Registry();
+
+// Add a default label which is added to all metrics
+register.setDefaultLabels({
+  app: process.env.SERVICE_NAME || 'unknown-service',
+  version: process.env.npm_package_version || '1.0.0'
+});
+
+// Enable the collection of default metrics
+promClient.collectDefaultMetrics({ register });
+
+// Custom metrics
+export const httpRequestDuration = new promClient.Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'Duration of HTTP requests in seconds',
+  labelNames: ['method', 'route', 'status_code'],
+  buckets: [0.1, 0.5, 1, 2, 5, 10]
+});
+
+export const httpRequestsTotal = new promClient.Counter({
+  name: 'http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'route', 'status_code']
+});
+
+export const activeConnections = new promClient.Gauge({
+  name: 'active_connections',
+  help: 'Number of active connections'
+});
+
+export const databaseQueryDuration = new promClient.Histogram({
+  name: 'database_query_duration_seconds',
+  help: 'Duration of database queries in seconds',
+  labelNames: ['operation', 'collection'],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5]
+});
+
+export const databaseQueriesTotal = new promClient.Counter({
+  name: 'database_queries_total',
+  help: 'Total number of database queries',
+  labelNames: ['operation', 'collection', 'status']
+});
+
+export const businessMetrics = {
+  albumsCreated: new promClient.Counter({
+    name: 'albums_created_total',
+    help: 'Total number of albums created'
+  }),
+
+  filesUploaded: new promClient.Counter({
+    name: 'files_uploaded_total',
+    help: 'Total number of files uploaded',
+    labelNames: ['file_type']
+  }),
+
+  usersRegistered: new promClient.Counter({
+    name: 'users_registered_total',
+    help: 'Total number of users registered'
+  }),
+
+  paymentsProcessed: new promClient.Counter({
+    name: 'payments_processed_total',
+    help: 'Total number of payments processed',
+    labelNames: ['status', 'method']
+  })
+};
+
+// Metrics endpoint handler
+export const metricsHandler = async (req: any, res: any) => {
+  try {
+    res.set('Content-Type', register.contentType);
+    const metrics = await register.metrics();
+    res.end(metrics);
+  } catch (error) {
+    res.status(500).end('Error generating metrics');
+  }
+};
+
+// Middleware to collect HTTP metrics
+export const metricsMiddleware = (req: any, res: any, next: any) => {
+  const start = Date.now();
+  const { method, url } = req;
+
+  // Increment active connections
+  activeConnections.inc();
+
+  res.on('finish', () => {
+    const duration = (Date.now() - start) / 1000; // Convert to seconds
+    const { statusCode } = res;
+
+    // Record metrics
+    httpRequestDuration
+      .labels(method, url, statusCode.toString())
+      .observe(duration);
+
+    httpRequestsTotal
+      .labels(method, url, statusCode.toString())
+      .inc();
+
+    // Decrement active connections
+    activeConnections.dec();
+  });
+
+  next();
+};
+
+export { register };

package/src/middleware/authMiddleware.test.ts

@@ -0,0 +1,104 @@
+import { Request, Response } from 'express';
+import jwt from 'jsonwebtoken';
+import { authenticateToken } from './authMiddleware';
+import { UserPayload } from '../types/auth';
+
+function mockReq(overrides: Partial<Request> = {}): Request {
+  return { cookies: {}, headers: {}, ...overrides } as unknown as Request;
+}
+
+function mockRes(): Response {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+}
+
+describe('authenticateToken', () => {
+  const ORIGINAL_ENV = process.env;
+  const next = jest.fn();
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV, JWT_SECRET: 'test-secret' };
+    next.mockClear();
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  const payload: UserPayload = { id: '1', email: 'user@example.com', name: 'Test User' };
+
+  it('attaches the decoded user and calls next for a valid cookie token', () => {
+    const token = jwt.sign(payload, 'test-secret');
+    const req = mockReq({ cookies: { access_token: token } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.user).toMatchObject({ id: '1', email: 'user@example.com' });
+  });
+
+  it('attaches an empty userGroups array when the token has no groups claim', () => {
+    const token = jwt.sign(payload, 'test-secret');
+    const req = mockReq({ cookies: { access_token: token } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(req.userGroups).toEqual([]);
+  });
+
+  it('attaches userGroups from the token when present', () => {
+    const token = jwt.sign({ ...payload, groups: ['group-1', 'group-2'] }, 'test-secret');
+    const req = mockReq({ cookies: { access_token: token } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(req.userGroups).toEqual(['group-1', 'group-2']);
+  });
+
+  it('accepts a Bearer token from the Authorization header', () => {
+    const token = jwt.sign(payload, 'test-secret');
+    const req = mockReq({ headers: { authorization: `Bearer ${token}` } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns 401 when no token is present', () => {
+    const req = mockReq();
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Access token required' });
+  });
+
+  it('returns 401 for an invalid token', () => {
+    const req = mockReq({ cookies: { access_token: 'not-a-real-token' } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ success: false, message: 'Invalid or expired token' });
+  });
+
+  it('returns 401 for a token signed with a different secret', () => {
+    const token = jwt.sign(payload, 'wrong-secret');
+    const req = mockReq({ cookies: { access_token: token } });
+    const res = mockRes();
+
+    authenticateToken(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+  });
+});

package/src/middleware/authMiddleware.ts

@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { requireEnv } from '../config/env';
+import { UserPayload } from '../types/auth';
+
+/**
+ * JWT authentication middleware
+ * Verifies JWT token and attaches user info (and its embedded groups) to
+ * the request — typed via the global `Express.Request` augmentation in
+ * `../types/auth`, no `(req as any)` cast needed.
+ */
+export function authenticateToken(req: Request, res: Response, next: NextFunction): void {
+  try {
+    const JWT_SECRET = requireEnv('JWT_SECRET');
+    const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
+
+    if (!token) {
+      res.status(401).json({ success: false, message: 'Access token required' });
+      return;
+    }
+
+    const user = jwt.verify(token, JWT_SECRET) as UserPayload;
+    req.user = user;
+    req.userGroups = user.groups ?? [];
+    next();
+  } catch (error) {
+    res.status(401).json({ success: false, message: 'Invalid or expired token' });
+  }
+}

package/src/middleware/corsMiddleware.test.ts

@@ -0,0 +1,58 @@
+import express from 'express';
+import request from 'supertest';
+import { createCorsMiddleware } from './corsMiddleware';
+import { errorHandler } from './errorHandler';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+function buildApp(origins: string) {
+  const app = express();
+  app.use(createCorsMiddleware({ origins }));
+  app.get('/ping', (_req, res) => res.json({ ok: true }));
+  app.use(errorHandler);
+  return app;
+}
+
+describe('createCorsMiddleware', () => {
+  const app = buildApp('https://allowed.example,https://also-allowed.example');
+
+  it('allows a request with no Origin header (server-to-server / health checks)', async () => {
+    const res = await request(app).get('/ping');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+  });
+
+  it('allows a whitelisted origin and echoes it back with credentials', async () => {
+    const res = await request(app).get('/ping').set('Origin', 'https://allowed.example');
+
+    expect(res.status).toBe(200);
+    expect(res.headers['access-control-allow-origin']).toBe('https://allowed.example');
+    expect(res.headers['access-control-allow-credentials']).toBe('true');
+  });
+
+  it('rejects an origin not on the whitelist', async () => {
+    const res = await request(app).get('/ping').set('Origin', 'https://evil.example');
+
+    expect(res.status).toBe(500);
+    expect(res.headers['access-control-allow-origin']).toBeUndefined();
+  });
+
+  it('falls back to process.env.CORS_ORIGIN when no origins option is given', async () => {
+    const ORIGINAL_ENV = process.env;
+    process.env = { ...ORIGINAL_ENV, CORS_ORIGIN: 'https://from-env.example' };
+
+    const envApp = express();
+    envApp.use(createCorsMiddleware());
+    envApp.get('/ping', (_req, res) => res.json({ ok: true }));
+    envApp.use(errorHandler);
+
+    const res = await request(envApp).get('/ping').set('Origin', 'https://from-env.example');
+    expect(res.status).toBe(200);
+    expect(res.headers['access-control-allow-origin']).toBe('https://from-env.example');
+
+    process.env = ORIGINAL_ENV;
+  });
+});

package/src/middleware/corsMiddleware.ts

@@ -0,0 +1,36 @@
+import cors from 'cors';
+import logger from '../logging/logger';
+
+export interface CorsMiddlewareOptions {
+  /**
+   * Comma-separated origin whitelist. Defaults to process.env.CORS_ORIGIN,
+   * read per-request so it works regardless of dotenv.config() timing.
+   */
+  origins?: string;
+  exposedHeaders?: string[];
+}
+
+/**
+ * Shared CORS middleware with an explicit origin whitelist.
+ * Requests without an Origin header (server-to-server, curl, health checks)
+ * are always allowed; browser requests must match the whitelist.
+ */
+export function createCorsMiddleware(options: CorsMiddlewareOptions = {}) {
+  return cors({
+    origin: (origin, callback) => {
+      const allowedOrigins = (options.origins ?? process.env.CORS_ORIGIN ?? '')
+        .split(',')
+        .map(o => o.trim())
+        .filter(Boolean);
+      if (!origin || allowedOrigins.includes(origin)) {
+        return callback(null, true);
+      }
+      logger.warn('Blocked CORS origin', { origin });
+      return callback(new Error('Not allowed by CORS: ' + origin));
+    },
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'x-correlation-id', 'x-session-id'],
+    exposedHeaders: options.exposedHeaders
+  });
+}

package/src/middleware/errorHandler.test.ts

@@ -0,0 +1,146 @@
+import express from 'express';
+import request from 'supertest';
+import { errorHandler } from './errorHandler';
+import { NotFoundError, ForbiddenError } from '../errors/HttpError';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+import logger from '../logging/logger';
+
+function namedError(name: string, message: string): Error {
+  const error = new Error(message);
+  error.name = name;
+  return error;
+}
+
+function buildApp() {
+  const app = express();
+  app.get('/boom', (_req, _res, next) => next(new Error('kaboom')));
+  app.get('/missing', (_req, _res, next) => next(new NotFoundError('Album not found')));
+  app.get('/forbidden', (_req, _res, next) => next(new ForbiddenError()));
+  app.get('/validation', (_req, _res, next) =>
+    next(namedError('ValidationError', 'CollageModel validation failed: title: Path `title` is required.'))
+  );
+  app.get('/cast', (_req, _res, next) => next(namedError('CastError', 'Cast to ObjectId failed for value "abc"')));
+  app.use(errorHandler);
+  return app;
+}
+
+describe('errorHandler', () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    (logger.error as jest.Mock).mockClear();
+    (logger.warn as jest.Mock).mockClear();
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it('logs the error and responds 500 with a generic message in production', async () => {
+    process.env.NODE_ENV = 'production';
+    const app = buildApp();
+
+    const res = await request(app).get('/boom');
+
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({
+      success: false,
+      error: 'Internal server error',
+      message: 'Something went wrong'
+    });
+    expect(logger.error).toHaveBeenCalledWith('Unhandled error:', expect.objectContaining({ error: 'kaboom' }));
+  });
+
+  it('includes the real error message and stack in development', async () => {
+    process.env.NODE_ENV = 'development';
+    const app = buildApp();
+
+    const res = await request(app).get('/boom');
+
+    expect(res.status).toBe(500);
+    expect(res.body.message).toBe('kaboom');
+    expect(res.body.stack).toBeDefined();
+  });
+
+  it('adds CORS headers to the error response for an allowed origin', async () => {
+    process.env.NODE_ENV = 'production';
+    const app = buildApp();
+
+    const res = await request(app).get('/boom').set('Origin', 'http://localhost:3000');
+
+    expect(res.headers['access-control-allow-origin']).toBe('http://localhost:3000');
+    expect(res.headers['access-control-allow-credentials']).toBe('true');
+  });
+
+  it('does not add CORS headers for a disallowed origin', async () => {
+    process.env.NODE_ENV = 'production';
+    const app = buildApp();
+
+    const res = await request(app).get('/boom').set('Origin', 'https://evil.example');
+
+    expect(res.headers['access-control-allow-origin']).toBeUndefined();
+  });
+
+  describe('typed HttpError instances', () => {
+    it('uses the error’s own status code and message, in production too', async () => {
+      process.env.NODE_ENV = 'production';
+      const app = buildApp();
+
+      const res = await request(app).get('/missing');
+
+      expect(res.status).toBe(404);
+      expect(res.body).toEqual({ success: false, error: 'NotFoundError', message: 'Album not found' });
+    });
+
+    it('logs at warn level, not error, and without a stack trace', async () => {
+      const app = buildApp();
+
+      await request(app).get('/forbidden');
+
+      expect(logger.warn).toHaveBeenCalledWith(
+        'Request failed:',
+        expect.objectContaining({ error: 'Access denied', statusCode: 403 })
+      );
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+
+    it('does not include a stack trace in the response body, even in development', async () => {
+      process.env.NODE_ENV = 'development';
+      const app = buildApp();
+
+      const res = await request(app).get('/missing');
+
+      expect(res.body.stack).toBeUndefined();
+    });
+  });
+
+  describe('Mongoose ValidationError / CastError', () => {
+    it('maps a ValidationError to 400, using its own message', async () => {
+      const app = buildApp();
+
+      const res = await request(app).get('/validation');
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({
+        success: false,
+        error: 'ValidationError',
+        message: 'CollageModel validation failed: title: Path `title` is required.'
+      });
+    });
+
+    it('maps a CastError (e.g. an invalid ObjectId) to 400', async () => {
+      const app = buildApp();
+
+      const res = await request(app).get('/cast');
+
+      expect(res.status).toBe(400);
+      expect(res.body.error).toBe('CastError');
+    });
+  });
+});