@tumbaland/backend-core 1.17.0 → 1.19.0

package/dist/utils/permissionUtils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Simple permission helper that builds query filters for group-based access
+ * This avoids external API calls and can be used in database queries directly
+ */
+/**
+ * Build a MongoDB query for resources accessible by a user
+ * @param userId - The user's ID
+ * @param groupIds - Array of group IDs the user belongs to (optional)
+ * @param includePublic - Whether to include public resources
+ */
+export declare function buildAccessQuery(userId: string, groupIds?: string[], includePublic?: boolean): {
+    $or: ({
+        userId: string;
+    } | {
+        groupId: {
+            $in: string[];
+        };
+    } | {
+        isPublic: boolean;
+    })[];
+};
+/**
+ * Check if a user can access a specific resource
+ * @param userId - The requesting user's ID
+ * @param resourceUserId - The resource owner's ID
+ * @param resourceGroupId - The resource's group ID (if any)
+ * @param userGroupIds - Array of group IDs the user belongs to
+ * @param isResourcePublic - Whether the resource is public
+ */
+export declare function canAccessResource(userId: string, resourceUserId: string, resourceGroupId?: string, userGroupIds?: string[], isResourcePublic?: boolean): boolean;
+//# sourceMappingURL=permissionUtils.d.ts.map

package/dist/utils/permissionUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionUtils.d.ts","sourceRoot":"","sources":["../../src/utils/permissionUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAM,EAAO,EACvB,aAAa,GAAE,OAAe;;gBAGlB,MAAM;;iBAAgB;YAAE,GAAG,EAAE,MAAM,EAAE,CAAA;SAAE;;kBAAiB,OAAO;;EAgB5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,MAAM,EACxB,YAAY,GAAE,MAAM,EAAO,EAC3B,gBAAgB,GAAE,OAAe,GAChC,OAAO,CAkBT"}

package/dist/utils/permissionUtils.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Simple permission helper that builds query filters for group-based access
+ * This avoids external API calls and can be used in database queries directly
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAccessQuery = buildAccessQuery;
+exports.canAccessResource = canAccessResource;
+/**
+ * Build a MongoDB query for resources accessible by a user
+ * @param userId - The user's ID
+ * @param groupIds - Array of group IDs the user belongs to (optional)
+ * @param includePublic - Whether to include public resources
+ */
+function buildAccessQuery(userId, groupIds = [], includePublic = false) {
+    const conditions = [
+        { userId } // User's own resources
+    ];
+    // Add group-based access
+    if (groupIds.length > 0) {
+        conditions.push({ groupId: { $in: groupIds } });
+    }
+    // Add public resources if requested
+    if (includePublic) {
+        conditions.push({ isPublic: true });
+    }
+    return { $or: conditions };
+}
+/**
+ * Check if a user can access a specific resource
+ * @param userId - The requesting user's ID
+ * @param resourceUserId - The resource owner's ID
+ * @param resourceGroupId - The resource's group ID (if any)
+ * @param userGroupIds - Array of group IDs the user belongs to
+ * @param isResourcePublic - Whether the resource is public
+ */
+function canAccessResource(userId, resourceUserId, resourceGroupId, userGroupIds = [], isResourcePublic = false) {
+    // Owner can always access their own resources
+    if (userId === resourceUserId) {
+        return true;
+    }
+    // Public resources are accessible to anyone
+    if (isResourcePublic) {
+        return true;
+    }
+    // If resource is associated with a group, check if user is in that group
+    if (resourceGroupId && userGroupIds.includes(resourceGroupId)) {
+        return true;
+    }
+    // No access
+    return false;
+}
+//# sourceMappingURL=permissionUtils.js.map

package/dist/utils/permissionUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionUtils.js","sourceRoot":"","sources":["../../src/utils/permissionUtils.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAQH,4CAsBC;AAUD,8CAwBC;AA9DD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC9B,MAAc,EACd,WAAqB,EAAE,EACvB,gBAAyB,KAAK;IAE9B,MAAM,UAAU,GAEZ;QACF,EAAE,MAAM,EAAE,CAAC,uBAAuB;KACnC,CAAC;IAEF,yBAAyB;IACzB,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,oCAAoC;IACpC,IAAI,aAAa,EAAE,CAAC;QAClB,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iBAAiB,CAC/B,MAAc,EACd,cAAsB,EACtB,eAAwB,EACxB,eAAyB,EAAE,EAC3B,mBAA4B,KAAK;IAEjC,8CAA8C;IAC9C,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4CAA4C;IAC5C,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yEAAyE;IACzE,IAAI,eAAe,IAAI,YAAY,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY;IACZ,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/response.d.ts

@@ -2,7 +2,7 @@ import { Response } from 'express';
 /**
  * Standard API response format
  */
-export interface ApiResponse<T = any> {
+export interface ApiResponse<T = unknown> {
     success: boolean;
     data?: T;
     message?: string;
@@ -12,11 +12,11 @@ export interface ApiResponse<T = any> {
 /**
  * Create a standardized API response
  */
-export declare function createApiResponse<T = any>(success: boolean, data?: T, message?: string, error?: string, correlationId?: string): ApiResponse<T>;
+export declare function createApiResponse<T = unknown>(success: boolean, data?: T, message?: string, error?: string, correlationId?: string): ApiResponse<T>;
 /**
  * Send a success response
  */
-export declare function sendSuccess<T = any>(res: Response, data?: T, message?: string, statusCode?: number, correlationId?: string): void;
+export declare function sendSuccess<T = unknown>(res: Response, data?: T, message?: string, statusCode?: number, correlationId?: string): void;
 /**
  * Send an error response
  */

package/dist/utils/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,GAAG,EACvC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CAAC,CAAC,CAAC,CAShB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EACjC,GAAG,EAAE,QAAQ,EACb,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,GAAE,MAAY,EACxB,aAAa,CAAC,EAAE,MAAM,QAIvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAY,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,QAIvB"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAC3C,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CAAC,CAAC,CAAC,CAShB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,GAAG,EAAE,QAAQ,EACb,IAAI,CAAC,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,GAAE,MAAY,EACxB,aAAa,CAAC,EAAE,MAAM,QAIvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAY,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,QAIvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "express-rate-limit": "^8.5.2",
     "helmet": "^8.0.0",
     "jsonwebtoken": "^9.0.3",
@@ -58,7 +58,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "mongoose": "^9.7.3"
   }
 }

package/src/app/shutdown.test.ts

@@ -0,0 +1,129 @@
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+jest.mock('../database/connection', () => ({
+  __esModule: true,
+  disconnectDB: jest.fn().mockResolvedValue(undefined)
+}));
+
+import type { Server } from 'http';
+import logger from '../logging/logger';
+import { disconnectDB } from '../database/connection';
+import { registerShutdown } from './shutdown';
+
+/** Minimal fake http.Server whose close() invokes its callback. */
+function fakeServer(closeErr?: Error): Server {
+  return {
+    close: jest.fn((cb?: (err?: Error) => void) => {
+      cb?.(closeErr);
+      return undefined as unknown as Server;
+    })
+  } as unknown as Server;
+}
+
+describe('registerShutdown', () => {
+  const listeners: Record<string, (...args: unknown[]) => void> = {};
+  let processOnSpy: jest.SpyInstance;
+  let exitSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    for (const key of Object.keys(listeners)) delete listeners[key];
+
+    processOnSpy = jest
+      .spyOn(process, 'on')
+      .mockImplementation((event: string | symbol, handler: (...args: unknown[]) => void) => {
+        listeners[event as string] = handler;
+        return process;
+      });
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation(((): never => undefined as never));
+  });
+
+  afterEach(() => {
+    processOnSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+  it('registers SIGINT and SIGTERM handlers', () => {
+    registerShutdown({ serviceName: 'svc' });
+    expect(Object.keys(listeners).sort()).toEqual(['SIGINT', 'SIGTERM']);
+  });
+
+  it('closes the server, disconnects the DB, and exits 0 on SIGTERM', async () => {
+    const server = fakeServer();
+    registerShutdown({ serviceName: 'svc', server });
+
+    listeners.SIGTERM();
+    await flush();
+
+    expect(server.close).toHaveBeenCalled();
+    expect(disconnectDB).toHaveBeenCalledWith('svc');
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(logger.info).toHaveBeenCalledWith('Received shutdown signal, closing gracefully', {
+      service: 'svc',
+      signal: 'SIGTERM'
+    });
+  });
+
+  it('runs the onShutdown hook before closing the server', async () => {
+    const order: string[] = [];
+    const server = {
+      close: jest.fn((cb?: (err?: Error) => void) => {
+        order.push('server');
+        cb?.();
+        return undefined as unknown as Server;
+      })
+    } as unknown as Server;
+    const onShutdown = jest.fn(async () => {
+      order.push('hook');
+    });
+
+    registerShutdown({ serviceName: 'svc', server, onShutdown });
+    listeners.SIGINT();
+    await flush();
+
+    expect(order).toEqual(['hook', 'server']);
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it('skips the DB disconnect when disconnectDatabase is false', async () => {
+    registerShutdown({ serviceName: 'svc', disconnectDatabase: false });
+
+    listeners.SIGTERM();
+    await flush();
+
+    expect(disconnectDB).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it('is idempotent — a second signal while shutting down is ignored', async () => {
+    const server = fakeServer();
+    registerShutdown({ serviceName: 'svc', server });
+
+    listeners.SIGTERM();
+    listeners.SIGINT();
+    await flush();
+
+    expect(server.close).toHaveBeenCalledTimes(1);
+    expect(exitSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('exits 1 when the server fails to close', async () => {
+    const server = fakeServer(new Error('close boom'));
+    registerShutdown({ serviceName: 'svc', server });
+
+    listeners.SIGTERM();
+    await flush();
+
+    expect(disconnectDB).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(logger.error).toHaveBeenCalledWith('Error during graceful shutdown', {
+      service: 'svc',
+      error: 'close boom'
+    });
+  });
+});

package/src/app/shutdown.ts

@@ -0,0 +1,81 @@
+import type { Server } from 'http';
+import logger from '../logging/logger';
+import { disconnectDB } from '../database/connection';
+
+export interface RegisterShutdownOptions {
+  /** Service name, used for log context and the DB disconnect. */
+  serviceName: string;
+  /** The HTTP server returned by `app.listen(...)`, closed before the DB. */
+  server?: Server;
+  /**
+   * Whether to close the MongoDB connection on shutdown. Defaults to `true`;
+   * set `false` for services that never call `connectDB` (e.g. file, public).
+   */
+  disconnectDatabase?: boolean;
+  /** Optional extra cleanup run before the server/DB are closed. */
+  onShutdown?: () => Promise<void> | void;
+  /**
+   * Force `process.exit` after this many ms if a graceful close hangs, so a
+   * stuck connection can't block a container rollout. Defaults to 10s.
+   */
+  forceExitAfterMs?: number;
+}
+
+/**
+ * Registers `SIGINT` and `SIGTERM` handlers that drain the service before the
+ * process exits: run the optional cleanup hook, stop accepting new HTTP
+ * connections, then close the MongoDB connection. `SIGTERM` matters most —
+ * it's the signal Docker/Kubernetes send on stop and rollout, and without a
+ * handler the process is force-killed with its DB connection still open.
+ *
+ * The handler is idempotent (a second signal while shutting down is ignored)
+ * and self-arms a force-exit timer so a hung close still terminates.
+ */
+export const registerShutdown = ({
+  serviceName,
+  server,
+  disconnectDatabase = true,
+  onShutdown,
+  forceExitAfterMs = 10_000
+}: RegisterShutdownOptions): void => {
+  let shuttingDown = false;
+
+  const shutdown = async (signal: string): Promise<void> => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.info('Received shutdown signal, closing gracefully', { service: serviceName, signal });
+
+    const forceExit = setTimeout(() => {
+      logger.error('Graceful shutdown timed out, forcing exit', { service: serviceName });
+      process.exit(1);
+    }, forceExitAfterMs);
+    // Don't let the timer itself keep the event loop alive.
+    forceExit.unref?.();
+
+    try {
+      if (onShutdown) await onShutdown();
+
+      if (server) {
+        await new Promise<void>((resolve, reject) => {
+          server.close((err) => (err ? reject(err) : resolve()));
+        });
+      }
+
+      if (disconnectDatabase) await disconnectDB(serviceName);
+
+      clearTimeout(forceExit);
+      process.exit(0);
+    } catch (error) {
+      clearTimeout(forceExit);
+      logger.error('Error during graceful shutdown', {
+        service: serviceName,
+        error: (error as Error)?.message
+      });
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGINT', () => void shutdown('SIGINT'));
+  process.on('SIGTERM', () => void shutdown('SIGTERM'));
+};

package/src/health/createHealthCheck.test.ts

@@ -0,0 +1,89 @@
+import { Request, Response } from 'express';
+import mongoose from 'mongoose';
+import { createHealthCheck } from './createHealthCheck';
+
+function mockRes(): Response {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+}
+
+describe('createHealthCheck', () => {
+  const config = { service: 'demo-service', description: 'Demo service' };
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('responds 200 with dependencies.mongodb "connected" when Mongo is up', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 1 } as never);
+    const res = mockRes();
+
+    await createHealthCheck(config)({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: 'ok',
+        service: 'demo-service',
+        type: 'backend',
+        version: '1.0.0',
+        description: 'Demo service',
+        dependencies: { mongodb: 'connected' }
+      })
+    );
+  });
+
+  it('responds 503 with dependencies.mongodb "disconnected" when Mongo is down', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 0 } as never);
+    const res = mockRes();
+
+    await createHealthCheck(config)({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(503);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'error', dependencies: { mongodb: 'disconnected' } })
+    );
+  });
+
+  it('honors an explicit version override', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockReturnValue({ readyState: 1 } as never);
+    const res = mockRes();
+
+    await createHealthCheck({ ...config, version: '2.3.4' })({} as Request, res);
+
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ version: '2.3.4' }));
+  });
+
+  it('responds 503 with a generic error body when reading connection state throws', async () => {
+    jest.spyOn(mongoose, 'connection', 'get').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    const res = mockRes();
+
+    await createHealthCheck(config)({} as Request, res);
+
+    expect(res.status).toHaveBeenCalledWith(503);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ status: 'error', service: 'demo-service', error: 'Health check failed' })
+    );
+  });
+
+  describe('checkDatabase: false (DB-less services)', () => {
+    it('always responds 200 ok without touching Mongo or emitting dependencies', async () => {
+      const connectionSpy = jest.spyOn(mongoose, 'connection', 'get');
+      const res = mockRes();
+
+      await createHealthCheck({ ...config, checkDatabase: false })({} as Request, res);
+
+      expect(connectionSpy).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(200);
+      const body = (res.json as jest.Mock).mock.calls[0][0];
+      expect(body).toEqual(
+        expect.objectContaining({ status: 'ok', service: 'demo-service', type: 'backend', description: 'Demo service' })
+      );
+      expect(body).not.toHaveProperty('dependencies');
+    });
+  });
+});

package/src/health/createHealthCheck.ts

@@ -0,0 +1,67 @@
+import { Request, Response } from 'express';
+import mongoose from 'mongoose';
+
+export interface HealthCheckConfig {
+  /** Service name reported in the body, e.g. `auth-service`. */
+  service: string;
+  /** Human-readable service description. */
+  description: string;
+  /** Reported version. Defaults to `1.0.0`. */
+  version?: string;
+  /**
+   * Whether readiness depends on the MongoDB connection. Defaults to `true`:
+   * the response reports `dependencies.mongodb` and returns 503 while
+   * disconnected. Set `false` for services with no database (e.g.
+   * public-service), which then always report `ok` with no `dependencies`.
+   */
+  checkDatabase?: boolean;
+}
+
+/**
+ * The single, unified `/health` readiness handler for every backend service.
+ *
+ * Response contract (identical across services):
+ *   { status, service, type: 'backend', timestamp, version, description }
+ * plus, when `checkDatabase` is `true` (the default), a
+ * `dependencies.mongodb` field and a 503 while the connection is down. A
+ * DB-less service (`checkDatabase: false`) omits `dependencies` and always
+ * reports `ok`. On an unexpected failure the handler returns 503 with a
+ * generic `error: 'Health check failed'` body.
+ *
+ * `/health/live` (liveness, no dependency checks) is mounted separately by
+ * `createBaseApp`.
+ */
+export const createHealthCheck = ({
+  service,
+  description,
+  version = '1.0.0',
+  checkDatabase = true
+}: HealthCheckConfig) => {
+  return async (_req: Request, res: Response): Promise<void> => {
+    const timestamp = new Date().toISOString();
+    const base = { service, type: 'backend', timestamp, version, description };
+
+    if (!checkDatabase) {
+      res.status(200).json({ status: 'ok', ...base });
+      return;
+    }
+
+    try {
+      const isMongoHealthy = mongoose.connection.readyState === 1; // 1 = connected
+
+      res.status(isMongoHealthy ? 200 : 503).json({
+        status: isMongoHealthy ? 'ok' : 'error',
+        ...base,
+        dependencies: {
+          mongodb: isMongoHealthy ? 'connected' : 'disconnected'
+        }
+      });
+    } catch {
+      res.status(503).json({
+        status: 'error',
+        ...base,
+        error: 'Health check failed'
+      });
+    }
+  };
+};

package/src/index.ts

@@ -3,12 +3,16 @@
 // App bootstrap
 export { createBaseApp } from './app/createBaseApp';
 export type { CreateBaseAppOptions } from './app/createBaseApp';
+export { registerShutdown } from './app/shutdown';
+export type { RegisterShutdownOptions } from './app/shutdown';
 
 // Logging
 export { default as logger } from './logging/logger';
 
 // Health checks
 export { healthCheck, healthLive, metricsHandler } from './health/healthController';
+export { createHealthCheck } from './health/createHealthCheck';
+export type { HealthCheckConfig } from './health/createHealthCheck';
 
 // Database
 export { connectDB, disconnectDB } from './database/connection';
@@ -34,6 +38,7 @@ export type { UserPayload } from './types/auth';
 export { generateCorrelationId, correlationMiddleware } from './utils/correlation';
 export { createApiResponse, sendSuccess, sendError } from './utils/response';
 export type { ApiResponse } from './utils/response';
+export { buildAccessQuery, canAccessResource } from './utils/permissionUtils';
 
 // Metrics
 export {

package/src/logging/logger.ts

@@ -33,7 +33,7 @@ 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}`,
+    (info) => `${info.timestamp} ${info.level}: ${String(info.message)}`,
   ),
 );
 

package/src/metrics/index.ts

@@ -1,4 +1,5 @@
 import promClient from 'prom-client';
+import { Request, Response, NextFunction } from 'express';
 
 // Create a Registry which registers the metrics
 const register = new promClient.Registry();
@@ -69,7 +70,7 @@ export const businessMetrics = {
 };
 
 // Metrics endpoint handler
-export const metricsHandler = async (req: any, res: any) => {
+export const metricsHandler = async (_req: Request, res: Response) => {
   try {
     res.set('Content-Type', register.contentType);
     const metrics = await register.metrics();
@@ -80,7 +81,7 @@ export const metricsHandler = async (req: any, res: any) => {
 };
 
 // Middleware to collect HTTP metrics
-export const metricsMiddleware = (req: any, res: any, next: any) => {
+export const metricsMiddleware = (req: Request, res: Response, next: NextFunction) => {
   const start = Date.now();
   const { method, url } = req;
 

package/src/middleware/errorHandler.ts

@@ -53,7 +53,7 @@ export const errorHandler: ErrorRequestHandler = (
       statusCode: known.statusCode,
       url: req.url,
       method: req.method,
-      correlationId: (req as any).correlationId
+      correlationId: req.correlationId
     });
   } else {
     logger.error('Unhandled error:', {
@@ -63,7 +63,7 @@ export const errorHandler: ErrorRequestHandler = (
       method: req.method,
       ip: req.ip,
       userAgent: req.get('User-Agent'),
-      correlationId: (req as any).correlationId
+      correlationId: req.correlationId
     });
   }
 

package/src/middleware/requestLogger.ts

@@ -1,4 +1,5 @@
 import morgan from 'morgan';
+import { Request, Response, NextFunction } from 'express';
 import logger from '../logging/logger';
 import { metricsMiddleware } from '../metrics';
 
@@ -24,7 +25,7 @@ export const requestLoggerWithMetrics = [requestLogger, metricsMiddleware];
  * Simple request logger for development
  * Logs basic request info with correlation ID
  */
-export const simpleRequestLogger = (req: any, res: any, next: any) => {
+export const simpleRequestLogger = (req: Request, res: Response, next: NextFunction) => {
   const start = Date.now();
   const correlationId = req.correlationId || 'unknown';
 

package/src/tracing/index.test.ts

@@ -6,12 +6,16 @@
  * resolution, parent-span-vs-context handling, the helper wrappers), using
  * the real (side-effect-free) @opentelemetry/api for trace/context/propagation.
  */
-const mockSpan = () => ({
-  setAttribute: jest.fn(),
-  addEvent: jest.fn(),
-  end: jest.fn(),
-  spanContext: jest.fn(() => ({ traceId: 't', spanId: 's', traceFlags: 1 }))
-});
+// A partial span: only the members these tests exercise are stubbed, cast to
+// the full Span type so it satisfies the now-typed tracing helpers. The jest
+// mocks remain reachable at runtime for the assertions below.
+const mockSpan = () =>
+  ({
+    setAttribute: jest.fn(),
+    addEvent: jest.fn(),
+    end: jest.fn(),
+    spanContext: jest.fn(() => ({ traceId: 't', spanId: 's', traceFlags: 1 }))
+  }) as unknown as Span;
 
 const mockTracer = { startSpan: jest.fn(() => mockSpan()) };
 const registerMock = jest.fn();
@@ -38,7 +42,7 @@ jest.mock('@opentelemetry/resources', () => ({
   resourceFromAttributes: resourceFromAttributesMock
 }));
 
-import { context } from '@opentelemetry/api';
+import { context, Span } from '@opentelemetry/api';
 import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 
 async function loadTracing() {