@discover-cloud/shared 1.0.0 → 1.0.2

package/dist/errors/http-errors.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InternalServerError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = void 0;
+exports.ServiceUnavailableError = exports.InternalServerError = exports.TooManyRequestsError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = void 0;
 const app_error_1 = require("./app-error");
+/**
+ * HTTP ERRORS
+ * ────────────
+ * Typed subclasses of AppError for every common HTTP error status.
+ * GlobalErrorHandler catches these via instanceof AppError and maps
+ * statusCode + code directly to the response.
+ *
+ * Usage:
+ *   throw new NotFoundError("Account not found");
+ *   throw new ConflictError("Email already in use");
+ *   throw new BadRequestError("Invalid input", { field: "email" });
+ */
 class BadRequestError extends app_error_1.AppError {
     constructor(message = "Bad Request", details) {
         super("BAD_REQUEST", 400, message, details);
@@ -38,9 +50,21 @@ class UnprocessableEntityError extends app_error_1.AppError {
     }
 }
 exports.UnprocessableEntityError = UnprocessableEntityError;
+class TooManyRequestsError extends app_error_1.AppError {
+    constructor(message = "Too Many Requests", details) {
+        super("TOO_MANY_REQUESTS", 429, message, details);
+    }
+}
+exports.TooManyRequestsError = TooManyRequestsError;
 class InternalServerError extends app_error_1.AppError {
     constructor(message = "Internal Server Error", details) {
         super("INTERNAL_SERVER_ERROR", 500, message, details);
     }
 }
 exports.InternalServerError = InternalServerError;
+class ServiceUnavailableError extends app_error_1.AppError {
+    constructor(message = "Service Unavailable", details) {
+        super("SERVICE_UNAVAILABLE", 503, message, details);
+    }
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;

package/dist/http/index.d.ts

@@ -0,0 +1 @@
+export * from "./service-client";

package/dist/http/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./service-client"), exports);

package/dist/http/service-client.d.ts

@@ -1,15 +1,31 @@
-import axios, { AxiosInstance } from "axios";
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
 import { Request } from "express";
+/**
+ * SERVICE CLIENT
+ * ───────────────
+ * HTTP client for service-to-service calls.
+ * Forwards the internal JWT and request ID from the current Express request.
+ *
+ * Fixes vs original:
+ *   - Removed `validateStatus: () => true` — it silently swallowed 4xx/5xx,
+ *     forcing every caller to manually check response.status. Removed so
+ *     axios throws naturally on error responses.
+ *   - `postWithAuth(url, data: any)` → `data: unknown` — no silent any
+ *   - requestId fallback now consistent with requestId middleware logic
+ *   - Added `patchWithAuth` and `deleteWithAuth` — common enough to include
+ *   - Retry only on network errors + 5xx (not 4xx — those are caller errors)
+ */
 export declare class ServiceClient {
     readonly http: AxiosInstance;
     constructor(baseURL: string);
     private setupRetry;
+    getWithAuth<T = unknown>(url: string, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    postWithAuth<T = unknown>(url: string, data: unknown, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    patchWithAuth<T = unknown>(url: string, data: unknown, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    deleteWithAuth<T = unknown>(url: string, req: Request, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
     /**
-     * The new magic method.
-     * Pass the current Express Request object, and it automatically
-     * extracts the Gateway's Bearer token and forwards it.
+     * Merges Authorization + x-request-id into any provided config.
+     * The internal JWT is forwarded as-is — the gateway already minted it.
      */
-    getWithAuth(url: string, req: Request): Promise<axios.AxiosResponse<any, any, {}>>;
-    postWithAuth(url: string, data: any, req: Request): Promise<axios.AxiosResponse<any, any, {}>>;
-    private createAuthHeader;
+    private mergeAuth;
 }

package/dist/http/service-client.js

@@ -6,12 +6,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const axios_retry_1 = __importDefault(require("axios-retry"));
+/**
+ * SERVICE CLIENT
+ * ───────────────
+ * HTTP client for service-to-service calls.
+ * Forwards the internal JWT and request ID from the current Express request.
+ *
+ * Fixes vs original:
+ *   - Removed `validateStatus: () => true` — it silently swallowed 4xx/5xx,
+ *     forcing every caller to manually check response.status. Removed so
+ *     axios throws naturally on error responses.
+ *   - `postWithAuth(url, data: any)` → `data: unknown` — no silent any
+ *   - requestId fallback now consistent with requestId middleware logic
+ *   - Added `patchWithAuth` and `deleteWithAuth` — common enough to include
+ *   - Retry only on network errors + 5xx (not 4xx — those are caller errors)
+ */
 class ServiceClient {
     constructor(baseURL) {
         this.http = axios_1.default.create({
             baseURL,
             timeout: 8000,
-            validateStatus: () => true
         });
         this.setupRetry();
     }
@@ -20,37 +34,55 @@ class ServiceClient {
             retries: 3,
             retryDelay: axios_retry_1.default.exponentialDelay,
             retryCondition: (err) => {
+                // Retry on network errors or 5xx only
+                // Do NOT retry 4xx — those are deterministic failures
                 if (axios_retry_1.default.isNetworkError(err))
                     return true;
-                return (err.response?.status ?? 0) >= 500;
-            }
+                const status = err.response?.status ?? 0;
+                return status >= 500;
+            },
         });
     }
-    /**
-     * The new magic method.
-     * Pass the current Express Request object, and it automatically
-     * extracts the Gateway's Bearer token and forwards it.
-     */
-    async getWithAuth(url, req) {
-        return this.http.get(url, this.createAuthHeader(req));
+    /* ----------------------------------------------------------------
+       Auth-forwarding methods
+       Pass the current Express Request to automatically forward:
+         - Authorization: Bearer <internal-jwt>
+         - x-request-id: <propagated request ID>
+    ---------------------------------------------------------------- */
+    async getWithAuth(url, req, config) {
+        return this.http.get(url, this.mergeAuth(req, config));
+    }
+    async postWithAuth(url, data, req, config) {
+        return this.http.post(url, data, this.mergeAuth(req, config));
     }
-    async postWithAuth(url, data, req) {
-        return this.http.post(url, data, this.createAuthHeader(req));
+    async patchWithAuth(url, data, req, config) {
+        return this.http.patch(url, data, this.mergeAuth(req, config));
     }
-    // --- Helper to extract and forward the token ---
-    createAuthHeader(req) {
+    async deleteWithAuth(url, req, config) {
+        return this.http.delete(url, this.mergeAuth(req, config));
+    }
+    /* ----------------------------------------------------------------
+       Private helpers
+    ---------------------------------------------------------------- */
+    /**
+     * Merges Authorization + x-request-id into any provided config.
+     * The internal JWT is forwarded as-is — the gateway already minted it.
+     */
+    mergeAuth(req, config) {
         const authHeader = req.headers.authorization;
-        // Express headers can technically be string arrays. 
-        // We grab the first item if it's an array, or fallback to a generated ID.
-        const rawReqId = req.headers["x-request-id"];
-        const reqId = Array.isArray(rawReqId)
-            ? rawReqId[0]
-            : rawReqId || `req_${Math.random().toString(36).slice(2)}`;
+        // req.id is set by requestId middleware — always a string at this point.
+        // Fall back to x-request-id header if somehow req.id isn't set yet.
+        const upstream = req.headers["x-request-id"];
+        const requestId = req.id
+            ?? (Array.isArray(upstream) ? upstream[0] : upstream)
+            ?? `fallback-${Date.now()}`;
         return {
+            ...config,
             headers: {
+                ...config?.headers,
                 ...(authHeader ? { Authorization: authHeader } : {}),
-                "x-request-id": reqId
-            }
+                "x-request-id": requestId,
+            },
         };
     }
 }

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export * from "./enums";
 export * from "./errors";
-export * from "./dto";
-export * from "./security";
+export * from "./dtos";
+export * from "./authorization";
 export * from "./utils";
 export * from "./middleware";
 export * from "./types";
 export * from "./jwt";
+export * from "./http";

package/dist/index.js

@@ -16,9 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./enums"), exports);
 __exportStar(require("./errors"), exports);
-__exportStar(require("./dto"), exports);
-__exportStar(require("./security"), exports);
+__exportStar(require("./dtos"), exports);
+__exportStar(require("./authorization"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./middleware"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./jwt"), exports);
+__exportStar(require("./http"), exports);

package/dist/jwt/index.d.ts

@@ -1,2 +1 @@
-export * from "./jwt-verifier";
-export * from "./service-client";
+export * from "./internal-jwt-verifier";

package/dist/jwt/index.js

@@ -14,5 +14,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./jwt-verifier"), exports);
-__exportStar(require("./service-client"), exports);
+__exportStar(require("./internal-jwt-verifier"), exports);

package/dist/jwt/internal-jwt-verifier.d.ts

@@ -0,0 +1,35 @@
+import { AccountRole, GlobalPermission } from "../enums";
+import { InternalJwtPayload, AccessContext } from "../types";
+import { PermissionCacheService } from "../authorization";
+export declare class InternalJwtVerifier {
+    private readonly permissionCache;
+    private readonly jwks;
+    private readonly issuer;
+    private readonly audience;
+    constructor(permissionCache: PermissionCacheService);
+    verifyInternal(token: string): Promise<InternalJwtPayload>;
+    buildAccessContext(token: string): Promise<{
+        payload: InternalJwtPayload;
+        context: AccessContext;
+    }>;
+    /**
+     * Returns true if the context has the given permission.
+     * Machine contexts always return false — they carry no user permissions.
+     */
+    static hasPermission(ctx: AccessContext, permission: GlobalPermission): boolean;
+    /**
+     * Throws JWTClaimValidationFailed if the permission is missing.
+     * Use in middleware for a one-liner gate:
+     *   InternalJwtVerifier.requirePermission(ctx, GlobalPermission.MANAGE_ACCOUNTS);
+     */
+    static requirePermission(ctx: AccessContext, permission: GlobalPermission): void;
+    /**
+     * Returns true if the context carries the given role.
+     * Machine contexts always return false.
+     */
+    static hasRole(ctx: AccessContext, role: AccountRole): boolean;
+    /**
+     * Throws JWTClaimValidationFailed if the role doesn't match.
+     */
+    static requireRole(ctx: AccessContext, role: AccountRole): void;
+}

package/dist/jwt/internal-jwt-verifier.js

@@ -0,0 +1,162 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalJwtVerifier = void 0;
+const jose = __importStar(require("jose"));
+/**
+ * INTERNAL JWT VERIFIER  (@discover-cloud/shared)
+ * ──────────────────────────────────────────────────
+ * Verifies the internal JWT forwarded by the API Gateway, resolves
+ * permissions from Redis, and builds the AccessContext for req.accessContext.
+ *
+ * Key source: Gateway JWKS
+ *   GET http://api-gateway:3000/.well-known/jwks.json
+ *
+ * Flow per request:
+ *   1. Verify JWT signature, iss, aud, exp, nbf, typ   (jose.jwtVerify)
+ *   2. Guard typ === "internal"                         (token confusion protection)
+ *   3. For human tokens: resolve perms from Redis       (derive from role on miss)
+ *   4. Build and return AccessContext
+ */
+const CLOCK_TOLERANCE_SECONDS = 30;
+const JWKS_CACHE_MAX_AGE_MS = 10 * 60 * 1000; // 10 minutes
+const JWKS_FETCH_TIMEOUT_MS = 5000;
+class InternalJwtVerifier {
+    constructor(permissionCache) {
+        this.permissionCache = permissionCache;
+        const gatewayJwksUri = process.env.GATEWAY_JWKS_URI ??
+            "http://api-gateway:3000/.well-known/jwks.json";
+        this.issuer = process.env.INTERNAL_JWT_ISSUER ?? "discover-cloud:api-gateway";
+        this.audience = process.env.INTERNAL_JWT_AUDIENCE ?? "discover-cloud:internal";
+        this.jwks = jose.createRemoteJWKSet(new URL(gatewayJwksUri), {
+            cacheMaxAge: JWKS_CACHE_MAX_AGE_MS,
+            timeoutDuration: JWKS_FETCH_TIMEOUT_MS,
+        });
+    }
+    /* ----------------------------------------------------------------
+       verifyInternal
+       Full cryptographic verification + typ guard + clock skew tolerance.
+       Returns the raw verified payload.
+  
+       Use when you need raw JWT claims (e.g. jti for blacklisting).
+       For everything else, use buildAccessContext().
+    ---------------------------------------------------------------- */
+    async verifyInternal(token) {
+        // jose.jwtVerify accepts string directly — the Uint8Array overload is
+        // for raw JWS. The type error comes from jose's union overloads; casting
+        // to the correct overload signature resolves it.
+        const { payload } = await jose.jwtVerify(token, this.jwks, {
+            issuer: this.issuer,
+            audience: this.audience,
+            algorithms: ["RS256"],
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+        });
+        // typ guard — rejects external tokens accidentally forwarded downstream
+        if (payload.typ !== "internal") {
+            throw new jose.errors.JWTClaimValidationFailed(`Token type mismatch: expected "internal", got "${String(payload.typ)}". ` +
+                `Ensure clients are not forwarding external tokens past the gateway.`, payload, "typ", "check_failed");
+        }
+        return payload;
+    }
+    /* ----------------------------------------------------------------
+       buildAccessContext
+       Primary method — called by RequireAuthMiddleware on every request.
+       Verifies the token, resolves permissions, returns payload + context.
+  
+       Usage in auth middleware:
+         const token = extractBearer(req);
+         const { payload, context } = await verifier.buildAccessContext(token);
+         req.internalAuth  = payload;
+         req.accessContext = context;
+    ---------------------------------------------------------------- */
+    async buildAccessContext(token) {
+        const payload = await this.verifyInternal(token);
+        // Machine token — no user context, no permission cache lookup
+        if (payload.isMachine === true) {
+            const machinePayload = payload;
+            const context = {
+                kind: "machine",
+                serviceId: machinePayload.serviceId,
+            };
+            return { payload, context };
+        }
+        // Human token — resolve permissions from Redis (derive from role on miss)
+        const humanPayload = payload;
+        const perms = await this.permissionCache.resolve(humanPayload.accountId, humanPayload.accountRole);
+        const context = {
+            kind: "human",
+            accountId: humanPayload.accountId,
+            accountRole: humanPayload.accountRole,
+            perms, // populated from cache — never from the JWT
+        };
+        return { payload, context };
+    }
+    /* ----------------------------------------------------------------
+       Static helpers — use on req.accessContext after auth middleware runs
+    ---------------------------------------------------------------- */
+    /**
+     * Returns true if the context has the given permission.
+     * Machine contexts always return false — they carry no user permissions.
+     */
+    static hasPermission(ctx, permission) {
+        return ctx.kind === "human" && ctx.perms.includes(permission);
+    }
+    /**
+     * Throws JWTClaimValidationFailed if the permission is missing.
+     * Use in middleware for a one-liner gate:
+     *   InternalJwtVerifier.requirePermission(ctx, GlobalPermission.MANAGE_ACCOUNTS);
+     */
+    static requirePermission(ctx, permission) {
+        if (!InternalJwtVerifier.hasPermission(ctx, permission)) {
+            throw new jose.errors.JWTClaimValidationFailed(`Missing required permission: ${permission}`, {}, "perms", "check_failed");
+        }
+    }
+    /**
+     * Returns true if the context carries the given role.
+     * Machine contexts always return false.
+     */
+    static hasRole(ctx, role) {
+        return ctx.kind === "human" && ctx.accountRole === role;
+    }
+    /**
+     * Throws JWTClaimValidationFailed if the role doesn't match.
+     */
+    static requireRole(ctx, role) {
+        if (!InternalJwtVerifier.hasRole(ctx, role)) {
+            throw new jose.errors.JWTClaimValidationFailed(`Missing required role: ${role}`, {}, "role", "check_failed");
+        }
+    }
+}
+exports.InternalJwtVerifier = InternalJwtVerifier;

package/dist/middleware/authorize.middleware.d.ts

@@ -0,0 +1,22 @@
+import { Request, Response, NextFunction } from "express";
+import { GlobalPermission } from "../enums";
+/**
+ * AUTHORIZE MIDDLEWARE
+ * ─────────────────────
+ * Permission-gates a route. Must run AFTER require-auth (depends on req.accessContext).
+ * Uses InternalJwtVerifier.hasPermission — permissions come from the Redis
+ * permission cache loaded by RequireAuthMiddleware, not from the JWT itself.
+ *
+ * Usage:
+ *   router.delete("/accounts/:id",
+ *     requireAuth,
+ *     authorize(GlobalPermission.DELETE_ACCOUNT),
+ *     controller.delete
+ *   );
+ */
+export declare const authorize: (permission: GlobalPermission) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * authorizeAny
+ * Passes if the context has AT LEAST ONE of the provided permissions.
+ */
+export declare const authorizeAny: (...permissions: GlobalPermission[]) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/authorize.middleware.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeAny = exports.authorize = void 0;
+const internal_jwt_verifier_1 = require("../jwt/internal-jwt-verifier");
+/**
+ * AUTHORIZE MIDDLEWARE
+ * ─────────────────────
+ * Permission-gates a route. Must run AFTER require-auth (depends on req.accessContext).
+ * Uses InternalJwtVerifier.hasPermission — permissions come from the Redis
+ * permission cache loaded by RequireAuthMiddleware, not from the JWT itself.
+ *
+ * Usage:
+ *   router.delete("/accounts/:id",
+ *     requireAuth,
+ *     authorize(GlobalPermission.DELETE_ACCOUNT),
+ *     controller.delete
+ *   );
+ */
+const authorize = (permission) => {
+    return (req, res, next) => {
+        // 1. Ensure RequireAuthMiddleware has already run
+        if (!req.accessContext) {
+            res.status(401).json({
+                success: false,
+                error: {
+                    message: "Unauthorized: No access context",
+                    code: "UNAUTHORIZED",
+                    requestId: req.id,
+                },
+            });
+            return;
+        }
+        // 2. Check permission against accessContext.perms (loaded from Redis)
+        if (!internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(req.accessContext, permission)) {
+            res.status(403).json({
+                success: false,
+                error: {
+                    message: `Forbidden: Missing permission ${permission}`,
+                    code: "FORBIDDEN",
+                    requestId: req.id,
+                },
+            });
+            return;
+        }
+        next();
+    };
+};
+exports.authorize = authorize;
+/**
+ * authorizeAny
+ * Passes if the context has AT LEAST ONE of the provided permissions.
+ */
+const authorizeAny = (...permissions) => {
+    return (req, res, next) => {
+        if (!req.accessContext) {
+            res.status(401).json({
+                success: false,
+                error: { message: "Unauthorized: No access context", code: "UNAUTHORIZED", requestId: req.id },
+            });
+            return;
+        }
+        const hasAny = permissions.some((p) => internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(req.accessContext, p));
+        if (!hasAny) {
+            res.status(403).json({
+                success: false,
+                error: {
+                    message: `Forbidden: Missing one of [${permissions.join(", ")}]`,
+                    code: "FORBIDDEN",
+                    requestId: req.id,
+                },
+            });
+            return;
+        }
+        next();
+    };
+};
+exports.authorizeAny = authorizeAny;

package/dist/middleware/error-handler.middleware.d.ts

@@ -0,0 +1,16 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * GLOBAL ERROR HANDLER
+ * ─────────────────────
+ * Centralized error handler for all Express services.
+ *
+ * Handles in order:
+ *   1. ZodError  → 400 with flattened validation details
+ *   2. AppError  → mapped statusCode + code
+ *   3. Unknown   → 500 Internal Server Error (internals never leaked)
+ *
+ * Every response includes requestId for traceability.
+ */
+export declare class GlobalErrorHandler {
+    static handle(err: unknown, req: Request, res: Response, _next: NextFunction): void;
+}

package/dist/middleware/error-handler.middleware.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GlobalErrorHandler = void 0;
+const zod_1 = require("zod");
+const errors_1 = require("../errors");
+const utils_1 = require("../utils");
+/**
+ * GLOBAL ERROR HANDLER
+ * ─────────────────────
+ * Centralized error handler for all Express services.
+ *
+ * Handles in order:
+ *   1. ZodError  → 400 with flattened validation details
+ *   2. AppError  → mapped statusCode + code
+ *   3. Unknown   → 500 Internal Server Error (internals never leaked)
+ *
+ * Every response includes requestId for traceability.
+ */
+class GlobalErrorHandler {
+    static handle(err, req, res, _next) {
+        if (process.env.NODE_ENV !== "production") {
+            console.error(`[req ${req.id}]`, err);
+        }
+        else {
+            console.error(`[req ${req.id}]`, err instanceof Error ? err.message : err);
+        }
+        // 1. Zod validation errors
+        if (err instanceof zod_1.ZodError) {
+            (0, utils_1.failure)(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten() // default flatten — preserves fieldErrors + formErrors + codes
+            );
+            return;
+        }
+        // 2. Known AppError subclasses — instanceof, never duck-typing
+        if (err instanceof errors_1.AppError) {
+            (0, utils_1.failure)(res, req, err.message, err.code, err.statusCode, err.details);
+            return;
+        }
+        // 3. Unexpected errors — never leak internals to the client
+        (0, utils_1.failure)(res, req, "Internal Server Error", "INTERNAL_SERVER_ERROR", 500);
+    }
+}
+exports.GlobalErrorHandler = GlobalErrorHandler;

package/dist/middleware/index.d.ts

@@ -1,5 +1,4 @@
-export * from "./error-handler";
-export * from "./validate";
-export * from "./request-id";
-export * from "./require-auth";
-export * from "./authorize";
+export * from "./error-handler.middleware";
+export * from "./validate.middleware";
+export * from "./request-id.middleware";
+export * from "./authorize.middleware";

package/dist/middleware/index.js

@@ -14,8 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./error-handler"), exports);
-__exportStar(require("./validate"), exports);
-__exportStar(require("./request-id"), exports);
-__exportStar(require("./require-auth"), exports);
-__exportStar(require("./authorize"), exports);
+__exportStar(require("./error-handler.middleware"), exports);
+__exportStar(require("./validate.middleware"), exports);
+__exportStar(require("./request-id.middleware"), exports);
+__exportStar(require("./authorize.middleware"), exports);

package/dist/middleware/request-id.middleware.d.ts

@@ -0,0 +1,20 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * REQUEST ID MIDDLEWARE
+ * ──────────────────────
+ * Attaches a unique request ID to req.id for distributed tracing.
+ *
+ * Priority:
+ *   1. x-request-id header forwarded by the API Gateway (or load balancer)
+ *   2. Generate a new UUID if no upstream header is present
+ *
+ * Fix vs original:
+ *   The original always generated a new UUID, breaking distributed tracing.
+ *   If the gateway mints a requestId and forwards it via x-request-id,
+ *   the downstream service must carry that same ID — otherwise logs across
+ *   services cannot be correlated.
+ *
+ * Also sets x-request-id on the response so clients and proxies can
+ *   correlate their logs with the service's logs.
+ */
+export declare const requestId: (req: Request, res: Response, next: NextFunction) => void;