@discover-cloud/shared 1.2.9 → 1.3.0

package/dist/messaging/rabbitmq.client.d.ts

@@ -0,0 +1,13 @@
+export declare class RabbitMQClient {
+    private connection;
+    private channel;
+    private url;
+    private exchangeName;
+    constructor(url: string);
+    connect(): Promise<void>;
+    publishEvent(routingKey: string, payload: any): Promise<void>;
+    subscribe(queueName: string, routingKey: string, handler: (payload: any) => Promise<void>, options?: {
+        prefetch?: number;
+    }): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/messaging/rabbitmq.client.js

@@ -0,0 +1,127 @@
+"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.RabbitMQClient = void 0;
+const amqplib = __importStar(require("amqplib"));
+class RabbitMQClient {
+    constructor(url) {
+        this.connection = null;
+        this.channel = null;
+        this.exchangeName = 'discovercloud.topic';
+        this.url = url;
+    }
+    async connect() {
+        if (this.connection && this.channel) {
+            return;
+        }
+        try {
+            this.connection = await amqplib.connect(this.url);
+            this.connection.on('error', (err) => {
+                console.error('RabbitMQ Connection Error:', err);
+            });
+            this.connection.on('close', () => {
+                console.warn('RabbitMQ Connection Closed. Reconnecting...');
+                this.connection = null;
+                this.channel = null;
+                setTimeout(() => this.connect(), 5000);
+            });
+            this.channel = await this.connection.createChannel();
+            // Ensure the main topic exchange exists
+            await this.channel.assertExchange(this.exchangeName, 'topic', { durable: true });
+            console.log('✅ Connected to RabbitMQ');
+        }
+        catch (error) {
+            console.error('❌ Failed to connect to RabbitMQ:', error);
+            setTimeout(() => this.connect(), 5000);
+        }
+    }
+    async publishEvent(routingKey, payload) {
+        if (!this.channel) {
+            throw new Error('RabbitMQ Channel not initialized');
+        }
+        const buffer = Buffer.from(JSON.stringify(payload));
+        this.channel.publish(this.exchangeName, routingKey, buffer, {
+            persistent: true,
+            contentType: 'application/json',
+            timestamp: Date.now(),
+        });
+    }
+    async subscribe(queueName, routingKey, handler, options = {}) {
+        if (!this.channel) {
+            throw new Error('RabbitMQ Channel not initialized');
+        }
+        if (options.prefetch) {
+            await this.channel.prefetch(options.prefetch);
+        }
+        // Dead Letter configuration
+        const dlxName = `${this.exchangeName}.dlx`;
+        const dlqName = `${queueName}.dlq`;
+        await this.channel.assertExchange(dlxName, 'topic', { durable: true });
+        await this.channel.assertQueue(dlqName, { durable: true });
+        await this.channel.bindQueue(dlqName, dlxName, routingKey);
+        // Assert main queue with DLX bindings
+        await this.channel.assertQueue(queueName, {
+            durable: true,
+            deadLetterExchange: dlxName,
+            deadLetterRoutingKey: routingKey,
+        });
+        await this.channel.bindQueue(queueName, this.exchangeName, routingKey);
+        this.channel.consume(queueName, async (msg) => {
+            if (!msg)
+                return;
+            try {
+                const payload = JSON.parse(msg.content.toString());
+                await handler(payload);
+                this.channel.ack(msg);
+            }
+            catch (error) {
+                console.error(`Error processing message from ${queueName}:`, error);
+                // Nack the message and don't requeue, so it goes to the DLX
+                this.channel.nack(msg, false, false);
+            }
+        });
+        console.log(`📡 Subscribed to queue [${queueName}] with routing key [${routingKey}]`);
+    }
+    async close() {
+        if (this.channel) {
+            await this.channel.close();
+        }
+        if (this.connection) {
+            await this.connection.close();
+        }
+        console.log('RabbitMQ connection closed.');
+    }
+}
+exports.RabbitMQClient = RabbitMQClient;

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

@@ -1,30 +1,10 @@
-import { Request, Response, NextFunction } from "express";
 /**
- * GLOBAL ERROR HANDLER  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Centralised Express error handler. Register as the last middleware in
- * every service's app.ts:
- *
- *   app.use(GlobalErrorHandler.handle);
- *
- * Handles in order:
- *   1. ZodError  → 400 VALIDATION_ERROR with flattened field errors
- *   2. AppError  → mapped statusCode + code (details forwarded to client)
- *   3. Unknown   → 500 INTERNAL_SERVER_ERROR (internals never leaked)
- *
- * Logging strategy:
- *   Development — full error object printed for stack traces during development.
- *   Production  — message only for AppError/Error (no stack, no details in logs).
- *                 Unknown errors log the raw value at warn level.
- *                 In production, a structured logger (Pino) replaces console.*
- *                 in each service — these console calls are captured by stdout.
- *
- * Security:
- *   Unknown (unexpected) errors never expose internals to the client.
- *   AppError.details IS forwarded — callers that set details on an AppError
- *   are intentionally choosing to surface that context (e.g. validation hints).
- *   Never put secrets, stack traces, or raw DB errors in AppError.details.
+ * @file error-handler.middleware.ts
+ * @description Central Express error handler. Register as the final middleware.
  */
-export declare class GlobalErrorHandler {
-    static handle(err: unknown, req: Request, res: Response, _next: NextFunction): void;
-}
+import { ErrorRequestHandler } from "express";
+import { ILogger } from "../utils";
+/**
+ * Creates global Express error middleware.
+ */
+export declare function createGlobalErrorHandler(logger?: ILogger): ErrorRequestHandler;

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

@@ -1,70 +1,79 @@
 "use strict";
+/**
+ * @file error-handler.middleware.ts
+ * @description Central Express error handler. Register as the final middleware.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GlobalErrorHandler = void 0;
+exports.createGlobalErrorHandler = createGlobalErrorHandler;
 const zod_1 = require("zod");
 const errors_1 = require("../errors");
 const utils_1 = require("../utils");
 /**
- * GLOBAL ERROR HANDLER  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Centralised Express error handler. Register as the last middleware in
- * every service's app.ts:
- *
- *   app.use(GlobalErrorHandler.handle);
- *
- * Handles in order:
- *   1. ZodError  → 400 VALIDATION_ERROR with flattened field errors
- *   2. AppError  → mapped statusCode + code (details forwarded to client)
- *   3. Unknown   → 500 INTERNAL_SERVER_ERROR (internals never leaked)
- *
- * Logging strategy:
- *   Development — full error object printed for stack traces during development.
- *   Production  — message only for AppError/Error (no stack, no details in logs).
- *                 Unknown errors log the raw value at warn level.
- *                 In production, a structured logger (Pino) replaces console.*
- *                 in each service — these console calls are captured by stdout.
- *
- * Security:
- *   Unknown (unexpected) errors never expose internals to the client.
- *   AppError.details IS forwarded — callers that set details on an AppError
- *   are intentionally choosing to surface that context (e.g. validation hints).
- *   Never put secrets, stack traces, or raw DB errors in AppError.details.
+ * Detects malformed JSON thrown by express.json().
  */
-class GlobalErrorHandler {
-    static handle(err, req, res, _next) {
-        // ── Logging ──────────────────────────────────────────────────────────
-        if (process.env["NODE_ENV"] !== "production") {
-            // Full object in development — stack traces + details are useful locally.
-            console.error(`[req ${req.id}]`, err);
-        }
-        else if (err instanceof Error) {
-            // Production: message only — no stack, no details, no internal paths.
-            console.error(`[req ${req.id}] ${err.name}: ${err.message}`);
-        }
-        else {
-            // Non-Error throw (string, object, etc.) — log at warn; this should not happen.
-            console.warn(`[req ${req.id}] Non-Error thrown:`, typeof err);
+function isMalformedJsonError(err) {
+    return (err instanceof SyntaxError &&
+        "status" in err &&
+        typeof err.status === "number" &&
+        "body" in err);
+}
+/**
+ * Converts any thrown value into Error.
+ */
+function normalizeError(err) {
+    if (err instanceof Error) {
+        return err;
+    }
+    if (typeof err === "string") {
+        return new Error(err);
+    }
+    return new Error(JSON.stringify(err));
+}
+/**
+ * Creates global Express error middleware.
+ */
+function createGlobalErrorHandler(logger = utils_1.noopLogger) {
+    return (err, req, res, _next) => {
+        const error = normalizeError(err);
+        const requestId = req.requestContext?.requestId ?? req.id;
+        /**
+         * Malformed JSON
+         */
+        if (isMalformedJsonError(err) && err.status === 400) {
+            logger.warn({ requestId, err: error }, "Malformed JSON payload");
+            (0, utils_1.failure)(res, req, "Invalid JSON payload", "BAD_REQUEST", 400);
+            return;
         }
-        // ── 1. Zod validation errors ─────────────────────────────────────────
+        /**
+         * Validation failures
+         */
         if (err instanceof zod_1.ZodError) {
-            // flatten() groups errors into fieldErrors (keyed by path) and formErrors
-            // (top-level). This shape is stable across Zod versions and is what
-            // clients should key on for field-level error display.
+            logger.warn({ requestId, err: error }, "Request validation failed");
             (0, utils_1.failure)(res, req, "Validation failed", "VALIDATION_ERROR", 400, err.flatten());
             return;
         }
-        // ── 2. Known AppError subclasses ─────────────────────────────────────
-        // instanceof check — no duck-typing, no accidental matches.
-        // AppError.details is caller-controlled context (e.g. validation hints)
-        // and is intentionally forwarded to the client.
+        /**
+         * Known application errors
+         */
         if (err instanceof errors_1.AppError) {
+            const payload = {
+                requestId,
+                code: err.code,
+                err: error,
+            };
+            if (err.statusCode >= 500) {
+                logger.error(payload, err.message);
+            }
+            else {
+                logger.warn(payload, err.message);
+            }
             (0, utils_1.failure)(res, req, err.message, err.code, err.statusCode, err.details);
             return;
         }
-        // ── 3. Unexpected errors — never leak internals ───────────────────────
-        // Generic 500 with no details. The actual error is logged above (production:
-        // message only; development: full object). Nothing internal reaches the client.
+        /**
+         * Unknown crashes
+         */
+        logger.error({ requestId, err: error }, "Unhandled exception");
         (0, utils_1.failure)(res, req, "Internal Server Error", "INTERNAL_SERVER_ERROR", 500);
-    }
+    };
 }
-exports.GlobalErrorHandler = GlobalErrorHandler;

package/dist/middleware/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./error-handler.middleware";
 export * from "./validate.middleware";
-export * from "./request-id.middleware";
-export * from "./authorize.middleware";
-export * from "./validated-merge.middleware";
-export * from "./require-internal.middleware";
+export * from "./request-context.middleware";
+export * from "./require-machine.middleware";
 export * from "./require-auth.middleware";
-export * from "./require-human.middleware";
+export * from "./require-user.middleware";
+export * from "./require-org-permission.middleware";
+export * from "./require-workspace-permission.middleware";
+export * from "./require-platform-permission.middleware";
+export * from "./require-org-permission-from-body.middleware";

package/dist/middleware/index.js

@@ -16,9 +16,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./error-handler.middleware"), exports);
 __exportStar(require("./validate.middleware"), exports);
-__exportStar(require("./request-id.middleware"), exports);
-__exportStar(require("./authorize.middleware"), exports);
-__exportStar(require("./validated-merge.middleware"), exports);
-__exportStar(require("./require-internal.middleware"), exports);
+__exportStar(require("./request-context.middleware"), exports);
+__exportStar(require("./require-machine.middleware"), exports);
 __exportStar(require("./require-auth.middleware"), exports);
-__exportStar(require("./require-human.middleware"), exports);
+__exportStar(require("./require-user.middleware"), exports);
+__exportStar(require("./require-org-permission.middleware"), exports);
+__exportStar(require("./require-workspace-permission.middleware"), exports);
+__exportStar(require("./require-platform-permission.middleware"), exports);
+__exportStar(require("./require-org-permission-from-body.middleware"), exports);

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

@@ -0,0 +1,17 @@
+/**
+ * @file request-context.middleware.ts
+ * @description Express middleware to assign request tracing and audit metadata context.
+ */
+import { Request, Response, NextFunction } from "express";
+/**
+ * Attaches request metadata used for:
+ * - distributed tracing
+ * - audit logs
+ * - debugging correlation
+ *
+ * @param {Request}      req  - Express request object.
+ * @param {Response}     res  - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
+ * @returns {void}
+ */
+export declare const requestContext: (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/request-context.middleware.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * @file request-context.middleware.ts
+ * @description Express middleware to assign request tracing and audit metadata context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContext = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Normalizes IPv4-mapped IPv6 addresses.
+ *
+ * @param {string | null} ip - Raw IP.
+ * @returns {string | null} Normalized IP.
+ */
+function normalizeIp(ip) {
+    if (!ip) {
+        return null;
+    }
+    if (ip === "::1") {
+        return "127.0.0.1";
+    }
+    if (ip.startsWith("::ffff:")) {
+        return ip.substring(7);
+    }
+    return ip;
+}
+/**
+ * Resolves original client IP forwarded by the API Gateway.
+ *
+ * Priority:
+ * 1. x-forwarded-for
+ * 2. x-real-ip
+ * 3. socket fallback (local development only)
+ *
+ * @param {Request} req - Express request object.
+ * @returns {string | null} Client IP address.
+ */
+function resolveClientIp(req) {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (forwarded) {
+        const value = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+        return normalizeIp(value.split(",")[0].trim());
+    }
+    const realIp = req.headers["x-real-ip"];
+    if (realIp) {
+        return normalizeIp(Array.isArray(realIp) ? realIp[0] : realIp);
+    }
+    return normalizeIp(req.socket.remoteAddress ?? null);
+}
+/**
+ * Attaches request metadata used for:
+ * - distributed tracing
+ * - audit logs
+ * - debugging correlation
+ *
+ * @param {Request}      req  - Express request object.
+ * @param {Response}     res  - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
+ * @returns {void}
+ */
+const requestContext = (req, res, next) => {
+    const upstream = req.headers["x-request-id"];
+    const requestId = Array.isArray(upstream) ? upstream[0] : (upstream ?? (0, crypto_1.randomUUID)());
+    req.id = requestId;
+    req.requestContext = {
+        requestId,
+        ipAddress: resolveClientIp(req),
+        userAgent: req.headers["user-agent"] ?? null,
+    };
+    res.setHeader("x-request-id", requestId);
+    next();
+};
+exports.requestContext = requestContext;

package/dist/middleware/require-auth.middleware.d.ts

@@ -1,85 +1,32 @@
+/**
+ * @file require-auth.middleware.ts
+ * @description Authentication boundary middleware. Verifies the internal gateway JWT,
+ * builds the auth context, and gates endpoints.
+ */
 import { Request, Response, NextFunction } from "express";
-import { AccountRole, GlobalPermission } from "../enums";
 import { ILogger } from "../utils";
-import { InternalJwtVerifier } from "../jwt/internal-jwt-verifier";
+import { UserJwtVerifier } from "../jwt/user-jwt-verifier";
 /**
- * REQUIRE AUTH MIDDLEWARE  (@discover-cloud/shared)
- * ─────────────────────────────────────────────────────────────────────────
- * Verifies the internal JWT, resolves permissions from the Redis cache,
- * and attaches the typed AccessContext to req.accessContext.
- *
- * Moved to shared so every downstream service (auth, user, cloud, insights)
- * uses the same verified implementation rather than maintaining their own copy.
- *
- * Token extraction:
- *   Reads a Bearer token from the Authorization header.
- *   Does not support cookie-based auth — that is the API gateway's responsibility.
- *
- * On success:
- *   req.internalAuth  → raw verified JWT payload (use for jti, caller, requestId)
- *   req.accessContext → clean typed context (use in controllers and services)
- *
- * On failure:
- *   Returns a structured error response and does NOT call next().
- *   next(err) is only called for genuinely unexpected errors (not auth failures).
- *
- * Inline guards (requirePermission, requireRole):
- *   Convenience methods for single-route guards. For router-level permission
- *   enforcement, prefer the standalone factories in permission.middleware.ts —
- *   they don't require a reference to this class instance.
- *
- * Logging:
- *   Unexpected errors are logged at "error" level with requestId for correlation.
- *   Auth failures (expired, invalid token) are intentionally not logged at error
- *   level — they are client errors, not server faults.
- *
- * Usage in each service's app.ts:
- *   import { RequireAuthMiddleware } from "@discover-cloud/shared";
- *
- *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, logger);
- *   router.use(requireAuth.handle);
+ * Middleware handling authentication validation.
+ * Extracts the JWT, verifies it via UserJwtVerifier, and attaches the AuthContext.
  */
 export declare class RequireAuthMiddleware {
     private readonly verifier;
     private readonly logger;
-    constructor(verifier: InternalJwtVerifier, logger?: ILogger);
     /**
-     * Core authentication middleware.
-     * Apply via: router.use(requireAuth.handle) or router.get("/", requireAuth.handle, controller.x)
+     * @param {UserJwtVerifier} verifier - The token verification engine.
+     * @param {ILogger}             [logger] - Optional logger instance.
      */
-    handle: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+    constructor(verifier: UserJwtVerifier, logger?: ILogger);
     /**
-     * Inline permission guard — use when this class instance is available at the call site.
-     * For router-level guards, prefer requireGlobalPermission() from permission.middleware.ts.
+     * Core Express middleware handler for authenticating requests.
      *
-     * Usage: router.get("/", requireAuth.handle, requireAuth.requirePermission(P.READ_ACCOUNTS), controller.list)
-     */
-    requirePermission: (permission: GlobalPermission) => (req: Request, res: Response, next: NextFunction) => void;
-    /**
-     * Inline role guard — use when this class instance is available at the call site.
-     *
-     * Prefer permission-based guards over role-based guards where possible.
-     * Role checks are appropriate for coarse access gates (e.g. "only admins enter this router").
-     */
-    requireRole: (role: AccountRole) => (req: Request, res: Response, next: NextFunction) => void;
-    /**
-     * Extracts the Bearer token from the Authorization header.
-     * Returns null (not an error) if the header is absent or malformed —
-     * callers decide how to handle the missing token.
+     * @param {Request}      req  - Express request object.
+     * @param {Response}     res  - Express response object.
+     * @param {NextFunction} next - Express next function.
+     * @returns {Promise<void>}
      */
+    handle: (req: Request, res: Response, next: NextFunction) => Promise<void>;
     private extractBearer;
-    /**
-     * Maps jose verification errors to appropriate HTTP responses.
-     *
-     * Error categories:
-     *   JWTExpired              → 401 TOKEN_EXPIRED    (client should refresh)
-     *   JWTClaimValidationFailed,
-     *   JWSSignatureVerificationFailed,
-     *   JWSInvalid, JWTInvalid → 401 INVALID_TOKEN    (client should re-login)
-     *   Anything else           → 503 SERVICE_UNAVAILABLE (unexpected — log at error)
-     *
-     * Security note: generic "invalid token" messages are intentional.
-     * Never expose which specific claim failed — that aids token forgery attempts.
-     */
     private handleJwtError;
 }