@medi-car-bd/mcb-shared-auth 0.0.17 → 0.0.19

package/README.md

@@ -26,6 +26,16 @@ npm install @medi-car-bd/mcb-shared-auth
 Requires **Express 4** as a peer dependency (`^4.18.2`). The package targets
 CommonJS and ships type declarations.
 
+## Operational helpers
+
+Shared so every service behaves the same under an orchestrator:
+
+- `validateEnv({ service, required, secrets })` exits at startup naming every missing variable, and in production rejects secrets shorter than 32 characters or obvious placeholders.
+- `healthHandler(service)` is a liveness probe with no dependencies.
+- `readyHandler(service, { database: () => prisma.$queryRaw\`SELECT 1\` })` returns 200 only when every check passes, otherwise 503. List only dependencies the service cannot work without; the response names failed checks but never the underlying error.
+- `installGracefulShutdown(server, [cleanup, ...])` handles SIGTERM/SIGINT by draining the server, running the cleanups, then exiting, with a hard timeout.
+- `verifyAccessToken(token)` is the single access-token check used by `authenticate` and by Socket.IO handshakes.
+
 ## Quick start
 
 ### Protect a route

package/dist/middlewares/authenticate.d.ts

@@ -3,4 +3,15 @@ import jwt from "jsonwebtoken";
 export type AuthenticatedRequest = Request & {
     user?: jwt.JwtPayload & Record<string, unknown>;
 };
+/**
+ * Verifies an access token and returns its claims, or throws.
+ *
+ * Shared by the HTTP middleware and by Socket.IO handshakes so that every
+ * entry point applies the same checks. The algorithm, audience and issuer are
+ * pinned to what the auth service signs with, so a token minted for another
+ * purpose is not accepted. Refresh tokens share the secret, audience and
+ * issuer; only `type` distinguishes them, and one must never act as an access
+ * token.
+ */
+export declare const verifyAccessToken: (token: string) => jwt.JwtPayload & Record<string, unknown>;
 export declare const authenticate: (req: AuthenticatedRequest, _res: Response, next: NextFunction) => void;

package/dist/middlewares/authenticate.js

@@ -3,10 +3,37 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authenticate = void 0;
+exports.authenticate = exports.verifyAccessToken = void 0;
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const config_1 = require("../config");
 const utils_1 = require("../utils");
+/**
+ * Verifies an access token and returns its claims, or throws.
+ *
+ * Shared by the HTTP middleware and by Socket.IO handshakes so that every
+ * entry point applies the same checks. The algorithm, audience and issuer are
+ * pinned to what the auth service signs with, so a token minted for another
+ * purpose is not accepted. Refresh tokens share the secret, audience and
+ * issuer; only `type` distinguishes them, and one must never act as an access
+ * token.
+ */
+const verifyAccessToken = (token) => {
+    // Fail closed. Verifying against String(undefined) would accept tokens
+    // signed with the literal secret "undefined".
+    if (!config_1.JWT_SECRET) {
+        throw new utils_1.AppError("Authentication is not configured", 500);
+    }
+    const decoded = jsonwebtoken_1.default.verify(token, config_1.JWT_SECRET, {
+        algorithms: ["HS256"],
+        audience: "mcb-services",
+        issuer: "mcb-auth",
+    });
+    if (decoded.type !== "access") {
+        throw new utils_1.AppError("Invalid or expired token", 401);
+    }
+    return decoded;
+};
+exports.verifyAccessToken = verifyAccessToken;
 const authenticate = (req, _res, next) => {
     const header = req.headers.authorization;
     const token = (header && header.startsWith("Bearer ") && header.split(" ")[1]) ||
@@ -15,11 +42,13 @@ const authenticate = (req, _res, next) => {
         return next(new utils_1.AppError("Authentication required", 401));
     }
     try {
-        const decoded = jsonwebtoken_1.default.verify(token, String(config_1.JWT_SECRET));
-        req.user = decoded;
+        req.user = (0, exports.verifyAccessToken)(token);
         return next();
     }
-    catch (_a) {
+    catch (error) {
+        if (error instanceof utils_1.AppError && error.statusCode === 500) {
+            return next(error);
+        }
         return next(new utils_1.AppError("Invalid or expired token", 401));
     }
 };

package/dist/utils/appError.d.ts

@@ -3,7 +3,7 @@ export declare class AppError extends Error {
     status: "fail" | "error";
     isOperational: boolean;
     errmsg?: string;
-    code?: number;
+    code?: number | string;
     errors?: Record<string, unknown>;
     path?: string;
     value?: string | number;

package/dist/utils/authProxy.d.ts

@@ -0,0 +1,22 @@
+import type { Request, Response, NextFunction } from "express";
+/**
+ * Handlers that let a client expose the auth endpoints under its own prefix
+ * (/api/v1/billing/auth/login and so on), so its UI only ever talks to one
+ * service. They hold no auth logic: each request goes to mcb-auth-service and
+ * its response comes back unchanged, including the status, body and any
+ * Set-Cookie headers. Only the auth service issues tokens.
+ *
+ * The caller's Authorization header and cookies are forwarded as they are, and
+ * if the auth service is unreachable or too slow the caller gets a plain 502;
+ * the underlying error is logged, never returned, because it can name internal
+ * hosts.
+ */
+export declare const authProxy: (authServiceUrl: string, options?: {
+    timeoutMs?: number;
+}) => {
+    register: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+    login: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+    refresh: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+    logout: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+    me: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+};

package/dist/utils/authProxy.js

@@ -0,0 +1,84 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authProxy = void 0;
+const appError_1 = require("./appError");
+const logger_1 = require("./logger");
+const DEFAULT_TIMEOUT_MS = 10000;
+/** Request headers the auth service needs from the original caller. */
+const FORWARDED_HEADERS = [
+    "authorization",
+    "cookie",
+    "user-agent",
+    "x-correlation-id",
+];
+/**
+ * Handlers that let a client expose the auth endpoints under its own prefix
+ * (/api/v1/billing/auth/login and so on), so its UI only ever talks to one
+ * service. They hold no auth logic: each request goes to mcb-auth-service and
+ * its response comes back unchanged, including the status, body and any
+ * Set-Cookie headers. Only the auth service issues tokens.
+ *
+ * The caller's Authorization header and cookies are forwarded as they are, and
+ * if the auth service is unreachable or too slow the caller gets a plain 502;
+ * the underlying error is logged, never returned, because it can name internal
+ * hosts.
+ */
+const authProxy = (authServiceUrl, options = {}) => {
+    var _a;
+    const base = authServiceUrl.replace(/\/+$/, "");
+    const timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT_MS;
+    const forward = (endpoint, method) => (req, res, next) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        const headers = {
+            "content-type": "application/json",
+        };
+        for (const name of FORWARDED_HEADERS) {
+            const value = req.headers[name];
+            if (typeof value === "string")
+                headers[name] = value;
+        }
+        // The real caller, so the auth service's per-IP limit does not count every
+        // user of this service as one client.
+        if (req.ip)
+            headers["x-forwarded-for"] = req.ip;
+        let upstream;
+        let text;
+        try {
+            upstream = yield fetch(`${base}/api/v1/auth/auth/${endpoint}`, {
+                method,
+                headers,
+                body: method === "POST" ? JSON.stringify((_a = req.body) !== null && _a !== void 0 ? _a : {}) : undefined,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            text = yield upstream.text();
+        }
+        catch (error) {
+            logger_1.logger.error(`Auth service request failed (${endpoint}): ${error instanceof Error ? error.message : String(error)}`);
+            return next(new appError_1.AppError("Auth service unavailable", 502));
+        }
+        const contentType = upstream.headers.get("content-type");
+        if (contentType)
+            res.setHeader("content-type", contentType);
+        const cookies = upstream.headers.getSetCookie();
+        if (cookies.length > 0)
+            res.setHeader("set-cookie", cookies);
+        return res.status(upstream.status).send(text);
+    });
+    return {
+        register: forward("register", "POST"),
+        login: forward("login", "POST"),
+        refresh: forward("refresh", "POST"),
+        logout: forward("logout", "POST"),
+        me: forward("me", "GET"),
+    };
+};
+exports.authProxy = authProxy;

package/dist/utils/cors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser access rules shared by every service, so each UI can call its own
+ * client directly (for example the billing UI on :3001 calling the billing
+ * client on :8081) and nothing else can.
+ *
+ * Note that `cors({ origin: ["*"] })` does NOT allow everything: inside a list
+ * the cors package treats "*" as a literal origin, which matches no browser.
+ * That is what every service had before, and why direct UI calls failed.
+ */
+/**
+ * Reads a comma-separated origin list (normally the CORS_ORIGINS variable),
+ * falling back to `defaults` when it is unset or empty. Origins are compared
+ * exactly, so they must include scheme and port and have no trailing slash.
+ */
+export declare const parseOrigins: (raw: string | undefined, defaults?: string[]) => string[];
+/**
+ * Options for the `cors` middleware (and the same shape works for Socket.IO's
+ * `cors` setting). Requests without an Origin header
+ * (server-to-server calls, curl, health checks) are unaffected; a browser
+ * request from an origin not in the list gets no CORS headers and is blocked
+ * by the browser.
+ */
+export type BrowserAccess = {
+    origin: string[] | false;
+    credentials: boolean;
+};
+export declare const corsOptions: (origins: string[]) => BrowserAccess;

package/dist/utils/cors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.corsOptions = exports.parseOrigins = void 0;
+const logger_1 = require("./logger");
+/**
+ * Browser access rules shared by every service, so each UI can call its own
+ * client directly (for example the billing UI on :3001 calling the billing
+ * client on :8081) and nothing else can.
+ *
+ * Note that `cors({ origin: ["*"] })` does NOT allow everything: inside a list
+ * the cors package treats "*" as a literal origin, which matches no browser.
+ * That is what every service had before, and why direct UI calls failed.
+ */
+/**
+ * Reads a comma-separated origin list (normally the CORS_ORIGINS variable),
+ * falling back to `defaults` when it is unset or empty. Origins are compared
+ * exactly, so they must include scheme and port and have no trailing slash.
+ */
+const parseOrigins = (raw, defaults = []) => {
+    const listed = (raw !== null && raw !== void 0 ? raw : "")
+        .split(",")
+        .map((origin) => origin.trim().replace(/\/+$/, ""))
+        .filter(Boolean);
+    const origins = listed.length > 0 ? listed : defaults;
+    if (origins.includes("*")) {
+        // A wildcard cannot be combined with credentials, and in production it
+        // would let any website call the API from a signed-in user's browser.
+        logger_1.logger.warn('CORS_ORIGINS contains "*", which is ignored. List the UI origins explicitly.');
+    }
+    return origins.filter((origin) => origin !== "*");
+};
+exports.parseOrigins = parseOrigins;
+const corsOptions = (origins) => ({
+    origin: origins.length > 0 ? origins : false,
+    credentials: true,
+});
+exports.corsOptions = corsOptions;

package/dist/utils/globalError.js

@@ -29,6 +29,25 @@ const errorHandler = (err, req, res, _next) => {
     let statusCode = err.statusCode || 500;
     const status = err.status || "error";
     let { message } = err;
+    // Prisma rejecting the request itself is the caller's fault, not a server
+    // fault: unknown or mistyped fields, a reference to a missing record, or a
+    // record that no longer exists. Without this they all surfaced as 500s.
+    if (err.name === "PrismaClientValidationError") {
+        statusCode = 400;
+        message = "Invalid request: unknown or invalid fields";
+    }
+    else if (err.code === "P2002") {
+        statusCode = 409;
+        message = "A record with this value already exists";
+    }
+    else if (err.code === "P2003") {
+        statusCode = 400;
+        message = "Invalid request: it refers to a record that does not exist";
+    }
+    else if (err.code === "P2025") {
+        statusCode = 404;
+        message = "Not found";
+    }
     if (err.code === 11000) {
         statusCode = 400;
         const value = ((_b = (_a = err.errmsg) === null || _a === void 0 ? void 0 : _a.match(/(["'])(?:\\.|[^\\])*?\1/)) === null || _b === void 0 ? void 0 : _b[0]) || "value";
@@ -69,11 +88,9 @@ const errorHandler = (err, req, res, _next) => {
         default:
             break;
     }
-    res.status(statusCode).json({
-        state: status,
-        message,
-        stack: err.stack,
-    });
+    // Stack traces and internal error text are a disclosure risk in production.
+    const isProduction = process.env.NODE_ENV === "production";
+    res.status(statusCode).json(Object.assign({ state: status, message: isProduction && statusCode >= 500 ? "Internal server error" : message }, (isProduction ? {} : { stack: err.stack })));
     _1.logger.error(`${statusCode} - ${status} - ${req.originalUrl} - ${req.method} - ${req.ip} - ${correlationId} - ${err.message} - ${err.stack} `);
 };
 exports.errorHandler = errorHandler;

package/dist/utils/index.d.ts

@@ -11,3 +11,6 @@ export * from "./rotateRefreshToken";
 export * from "./generateAccessToken";
 export * from "./hashToken";
 export * from "./generateTokenId";
+export * from "./ops";
+export * from "./cors";
+export * from "./authProxy";

package/dist/utils/index.js

@@ -27,3 +27,6 @@ __exportStar(require("./rotateRefreshToken"), exports);
 __exportStar(require("./generateAccessToken"), exports);
 __exportStar(require("./hashToken"), exports);
 __exportStar(require("./generateTokenId"), exports);
+__exportStar(require("./ops"), exports);
+__exportStar(require("./cors"), exports);
+__exportStar(require("./authProxy"), exports);

package/dist/utils/limiter.d.ts

@@ -1 +1,22 @@
+import "../config";
+/**
+ * Per-caller request limit for a service. It counts each client address, so a
+ * service behind the gateway must also trust the gateway (see
+ * trustProxySetting), or every user counts as one caller.
+ *
+ * RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS override the defaults. The default
+ * matches the gateway's per-service limit: field apps on mobile networks share
+ * addresses, so a low ceiling throttles real users rather than attackers.
+ */
 export declare const limiter: import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * The value for Express's "trust proxy": which directly connected addresses may
+ * state the real client through X-Forwarded-For. By default that is this
+ * machine and private networks, where the gateway and the other services run.
+ * A caller connecting from a public address is not trusted, so it cannot fake
+ * its address with that header.
+ *
+ * TRUST_PROXY overrides it: a number of hops, "true", "false", or a
+ * comma-separated list of addresses or names such as "loopback, uniquelocal".
+ */
+export declare const trustProxySetting: (raw?: string | undefined) => string | number | boolean;

package/dist/utils/limiter.js

@@ -3,10 +3,52 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.limiter = void 0;
+exports.trustProxySetting = exports.limiter = void 0;
 const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+require("../config");
+const DEFAULT_MAX = 600;
+const DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+const positive = (raw, fallback) => {
+    const value = Number(raw);
+    return raw && Number.isFinite(value) && value > 0 ? value : fallback;
+};
+/**
+ * Per-caller request limit for a service. It counts each client address, so a
+ * service behind the gateway must also trust the gateway (see
+ * trustProxySetting), or every user counts as one caller.
+ *
+ * RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS override the defaults. The default
+ * matches the gateway's per-service limit: field apps on mobile networks share
+ * addresses, so a low ceiling throttles real users rather than attackers.
+ */
 exports.limiter = (0, express_rate_limit_1.default)({
-    max: 100, // 100 requests
-    windowMs: 15 * 60 * 1000, // 15 minutes
-    message: "Too many requests from this IP, please try again in an hour!", // message to send
+    max: positive(process.env.RATE_LIMIT_MAX, DEFAULT_MAX),
+    windowMs: positive(process.env.RATE_LIMIT_WINDOW_MS, DEFAULT_WINDOW_MS),
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: {
+        state: "fail",
+        message: "Too many requests, please try again later.",
+    },
 });
+/**
+ * The value for Express's "trust proxy": which directly connected addresses may
+ * state the real client through X-Forwarded-For. By default that is this
+ * machine and private networks, where the gateway and the other services run.
+ * A caller connecting from a public address is not trusted, so it cannot fake
+ * its address with that header.
+ *
+ * TRUST_PROXY overrides it: a number of hops, "true", "false", or a
+ * comma-separated list of addresses or names such as "loopback, uniquelocal".
+ */
+const trustProxySetting = (raw = process.env.TRUST_PROXY) => {
+    const value = raw === null || raw === void 0 ? void 0 : raw.trim();
+    if (!value)
+        return "loopback, uniquelocal";
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return /^\d+$/.test(value) ? Number(value) : value;
+};
+exports.trustProxySetting = trustProxySetting;

package/dist/utils/logger.js

@@ -28,6 +28,12 @@ exports.logger = (0, winston_1.createLogger)({
         }),
     ],
 });
+// Containers are expected to log to stdout: files inside a container are lost
+// when it is replaced and invisible to `docker logs` and log shippers. The
+// files above are kept for hosts that are not containerised.
+if (config_1.NODE_ENV === "production") {
+    exports.logger.add(new winston_1.transports.Console({ format: winston_1.format.json() }));
+}
 if (config_1.NODE_ENV !== "production") {
     exports.logger.add(new winston_1.transports.Console({
         format: winston_1.format.combine(winston_1.format.colorize(), winston_1.format.timestamp({

package/dist/utils/ops.d.ts

@@ -0,0 +1,38 @@
+import type { Server } from "http";
+import type { Request, Response } from "express";
+export type ValidateEnvOptions = {
+    service: string;
+    /** Variables that must be set and non-empty. */
+    required: string[];
+    /** Subset of variables holding secrets; checked for strength in production. */
+    secrets?: string[];
+};
+/**
+ * Returns a list of problems with the process environment, empty when it is
+ * fine. Pure, so it can be tested without exiting the process.
+ */
+export declare const findEnvProblems: ({ required, secrets }: ValidateEnvOptions, env?: NodeJS.ProcessEnv) => string[];
+/**
+ * Fails fast at startup. A service that boots with a missing secret otherwise
+ * looks healthy and then fails on every request, which is much harder to spot.
+ */
+export declare const validateEnv: (options: ValidateEnvOptions) => void;
+/** Liveness: the process is up and the event loop is responding. No dependencies. */
+export declare const healthHandler: (service: string) => (_req: Request, res: Response) => void;
+export type ReadinessChecks = Record<string, () => Promise<unknown>>;
+/**
+ * Readiness: 200 only when every check passes, otherwise 503. Only list
+ * dependencies the service cannot work without (its database). Optional ones
+ * such as Redis or Kafka must not appear here, or an outage of a nice-to-have
+ * would take the service out of rotation.
+ *
+ * The body names which checks failed but never the underlying error, which can
+ * contain hostnames and credentials.
+ */
+export declare const readyHandler: (service: string, checks: ReadinessChecks, timeoutMs?: number) => (_req: Request, res: Response) => Promise<void>;
+/**
+ * Stops accepting connections on SIGTERM/SIGINT, lets in-flight requests
+ * finish, runs the cleanups (close the database, etc.), then exits. A hard
+ * timeout guarantees the process cannot hang a rolling deploy.
+ */
+export declare const installGracefulShutdown: (server: Server, cleanups?: Array<() => Promise<unknown> | unknown>, timeoutMs?: number) => void;

package/dist/utils/ops.js

@@ -0,0 +1,155 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGracefulShutdown = exports.readyHandler = exports.healthHandler = exports.validateEnv = exports.findEnvProblems = void 0;
+const logger_1 = require("./logger");
+/**
+ * Operational helpers shared by every service: startup env validation,
+ * liveness and readiness handlers, and graceful shutdown. They live here so the
+ * services behave identically under an orchestrator instead of each growing its
+ * own slightly different copy.
+ */
+const PLACEHOLDER_SECRETS = new Set([
+    "secret",
+    "changeme",
+    "change-me",
+    "change_me",
+    "password",
+    "undefined",
+    "jwt_secret",
+]);
+const MIN_PRODUCTION_SECRET_LENGTH = 32;
+/**
+ * Returns a list of problems with the process environment, empty when it is
+ * fine. Pure, so it can be tested without exiting the process.
+ */
+const findEnvProblems = ({ required, secrets = [] }, env = process.env) => {
+    var _a, _b, _c;
+    const problems = [];
+    for (const name of required) {
+        if (!((_a = env[name]) === null || _a === void 0 ? void 0 : _a.trim()))
+            problems.push(`${name} is not set`);
+    }
+    const port = (_b = env.PORT) === null || _b === void 0 ? void 0 : _b.trim();
+    if (port && !/^\d+$/.test(port))
+        problems.push("PORT must be a number (it is not, so the server would bind to a random port)");
+    if (env.NODE_ENV === "production") {
+        for (const name of secrets) {
+            const value = (_c = env[name]) === null || _c === void 0 ? void 0 : _c.trim();
+            if (!value)
+                continue; // already reported as missing when required
+            if (value.length < MIN_PRODUCTION_SECRET_LENGTH ||
+                PLACEHOLDER_SECRETS.has(value.toLowerCase())) {
+                problems.push(`${name} is too weak for production (use at least ${MIN_PRODUCTION_SECRET_LENGTH} random characters)`);
+            }
+        }
+    }
+    return problems;
+};
+exports.findEnvProblems = findEnvProblems;
+/**
+ * Fails fast at startup. A service that boots with a missing secret otherwise
+ * looks healthy and then fails on every request, which is much harder to spot.
+ */
+const validateEnv = (options) => {
+    const problems = (0, exports.findEnvProblems)(options);
+    if (problems.length === 0)
+        return;
+    const message = `${options.service} cannot start:\n${problems
+        .map((p) => `  - ${p}`)
+        .join("\n")}`;
+    logger_1.logger.error(message);
+    console.error(message);
+    process.exit(1);
+};
+exports.validateEnv = validateEnv;
+/** Liveness: the process is up and the event loop is responding. No dependencies. */
+const healthHandler = (service) => (_req, res) => {
+    res.status(200).json({
+        status: "ok",
+        service,
+        uptimeSeconds: Math.round(process.uptime()),
+    });
+};
+exports.healthHandler = healthHandler;
+const withTimeout = (work, ms) => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("timeout")), ms);
+    work.then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+    }, (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+});
+/**
+ * Readiness: 200 only when every check passes, otherwise 503. Only list
+ * dependencies the service cannot work without (its database). Optional ones
+ * such as Redis or Kafka must not appear here, or an outage of a nice-to-have
+ * would take the service out of rotation.
+ *
+ * The body names which checks failed but never the underlying error, which can
+ * contain hostnames and credentials.
+ */
+const readyHandler = (service, checks, timeoutMs = 2000) => (_req, res) => __awaiter(void 0, void 0, void 0, function* () {
+    const results = {};
+    yield Promise.all(Object.entries(checks).map((_a) => __awaiter(void 0, [_a], void 0, function* ([name, check]) {
+        try {
+            yield withTimeout(check(), timeoutMs);
+            results[name] = "up";
+        }
+        catch (error) {
+            results[name] = "down";
+            logger_1.logger.warn(`${service} readiness check "${name}" failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })));
+    const ready = Object.values(results).every((r) => r === "up");
+    res.status(ready ? 200 : 503).json({
+        status: ready ? "ready" : "unavailable",
+        service,
+        checks: results,
+    });
+});
+exports.readyHandler = readyHandler;
+/**
+ * Stops accepting connections on SIGTERM/SIGINT, lets in-flight requests
+ * finish, runs the cleanups (close the database, etc.), then exits. A hard
+ * timeout guarantees the process cannot hang a rolling deploy.
+ */
+const installGracefulShutdown = (server, cleanups = [], timeoutMs = 10000) => {
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        var _a;
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger_1.logger.info(`Received ${signal}, shutting down`);
+        const force = setTimeout(() => {
+            logger_1.logger.error("Graceful shutdown timed out, forcing exit");
+            process.exit(1);
+        }, timeoutMs);
+        force.unref();
+        server.close(() => {
+            void Promise.allSettled(cleanups.map((fn) => Promise.resolve().then(fn))).then((results) => {
+                results.forEach((r) => {
+                    if (r.status === "rejected")
+                        logger_1.logger.warn(`Shutdown cleanup failed: ${String(r.reason)}`);
+                });
+                process.exit(0);
+            });
+        });
+        // Idle keep-alive connections would otherwise hold server.close() open.
+        (_a = server.closeIdleConnections) === null || _a === void 0 ? void 0 : _a.call(server);
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+};
+exports.installGracefulShutdown = installGracefulShutdown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medi-car-bd/mcb-shared-auth",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Shared authentication module for MCB applications",
   "packageManager": "pnpm@10.18.0",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     "lint": "eslint . --ext .ts,.tsx,.js,.jsx",
     "lint:fix": "eslint . --ext .ts,.tsx,.js,.jsx --fix",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "test": "tsc -p tsconfig.json && JWT_SECRET=unit-test-secret node --test dist/test/*.test.js"
   },
   "keywords": [
     "jwt",
@@ -55,7 +56,8 @@
     "express": "^4.18.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/test"
   ],
   "lint-staged": {
     "*.{ts,tsx,js,jsx}": [