@discover-cloud/shared 1.0.0 → 1.0.2

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

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestId = void 0;
+const crypto_1 = require("crypto");
+/**
+ * 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.
+ */
+const requestId = (req, res, next) => {
+    const upstream = req.headers["x-request-id"];
+    // Header can technically be a string array (multi-value) — take the first
+    const id = Array.isArray(upstream)
+        ? upstream[0]
+        : upstream ?? (0, crypto_1.randomUUID)();
+    req.id = id;
+    // Echo back on the response for client-side correlation
+    res.setHeader("x-request-id", id);
+    next();
+};
+exports.requestId = requestId;

package/dist/middleware/validate.middleware.d.ts

@@ -0,0 +1,26 @@
+import { Request, Response, NextFunction } from "express";
+import { ZodType } from "zod";
+/**
+ * VALIDATOR MIDDLEWARE
+ * ─────────────────────
+ * Validates and parses request input using a Zod schema.
+ * On success, attaches the parsed data to req.validated.
+ * On failure, passes a ZodError to GlobalErrorHandler → 400 response.
+ *
+ * Changes vs original:
+ *   - Added "headers" as a valid source (useful for API key / custom header validation)
+ *   - req.validated typed as unknown — consumers must narrow via z.infer at route level
+ *
+ * Usage:
+ *   router.post("/orders",
+ *     requireAuth,
+ *     Validator.validate(CreateOrderSchema, "body"),
+ *     controller.create
+ *   );
+ *
+ *   // In controller:
+ *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+ */
+export declare class Validator {
+    static validate<T>(schema: ZodType<T>, source?: "body" | "params" | "query" | "headers"): (req: Request, _res: Response, next: NextFunction) => void;
+}

package/dist/middleware/validate.middleware.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Validator = void 0;
+/**
+ * VALIDATOR MIDDLEWARE
+ * ─────────────────────
+ * Validates and parses request input using a Zod schema.
+ * On success, attaches the parsed data to req.validated.
+ * On failure, passes a ZodError to GlobalErrorHandler → 400 response.
+ *
+ * Changes vs original:
+ *   - Added "headers" as a valid source (useful for API key / custom header validation)
+ *   - req.validated typed as unknown — consumers must narrow via z.infer at route level
+ *
+ * Usage:
+ *   router.post("/orders",
+ *     requireAuth,
+ *     Validator.validate(CreateOrderSchema, "body"),
+ *     controller.create
+ *   );
+ *
+ *   // In controller:
+ *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+ */
+class Validator {
+    static validate(schema, source = "body") {
+        return (req, _res, next) => {
+            const result = schema.safeParse(req[source]);
+            if (!result.success) {
+                // ZodError propagates to GlobalErrorHandler → 400 with flatten()
+                next(result.error);
+                return;
+            }
+            // req.validated typed as unknown in express.d.ts
+            // Narrow to your schema type at the route/controller level
+            req.validated = result.data;
+            next();
+        };
+    }
+}
+exports.Validator = Validator;

package/dist/types/express.types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
+ * ───────────────────────────────────────────────
+ * Single source of truth for everything attached to Express's Request object
+ * and all internal JWT payload shapes.
+ *
+ * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ *   import "@discover-cloud/shared/types/express";
+ *
+ * ─── Permission flow ────────────────────────────────────────────────
+ *   JWT carries:        accountId + accountRole   (lean, no perms)
+ *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
+ *   AccessContext has:  perms                      (populated by auth middleware)
+ *
+ *   perms never touch the JWT — they live in the permission cache and are
+ *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ */
+import "express-serve-static-core";
+import { JWTPayload } from "jose";
+import { AccountRole } from "../enums";
+import { GlobalPermission } from "../enums";
+interface BaseInternalJwtPayload extends JWTPayload {
+    /**
+     * JWT ID — REQUIRED.
+     * Used for the Redis kill-switch (session revocation / account suspension).
+     * Overrides JWTPayload's optional jti with required.
+     */
+    jti: string;
+    /** typ discriminator — guards against token type confusion attacks */
+    typ: "internal";
+    /**
+     * The entity that last minted or forwarded this token.
+     *   "api-gateway"   → direct user-initiated request
+     *   "order-service" → service-to-service call on behalf of a user
+     * Used for audit logging and conditional authorization.
+     */
+    caller: string;
+    /**
+     * Propagated request ID for distributed tracing.
+     * Ties together logs across the entire service call chain.
+     */
+    requestId?: string;
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf: number;
+}
+/**
+ * Human JWT payload — issued on behalf of an authenticated user.
+ * Minted by the gateway after verifying an external JWT.
+ *
+ * accountRole is carried so the permission cache can derive perms
+ * from globalRolePermissions on a cold cache miss — without a DB call.
+ */
+export interface HumanInternalJwtPayload extends BaseInternalJwtPayload {
+    isMachine: false;
+    accountId: string;
+    accountRole: AccountRole;
+}
+/**
+ * Machine JWT payload — service-to-service calls with no user context.
+ * Intentionally carries NO user fields — absence is enforced by the type.
+ */
+export interface MachineInternalJwtPayload extends BaseInternalJwtPayload {
+    isMachine: true;
+    serviceId: string;
+}
+/** The full internal JWT payload union — use this in verifiers and auth middleware */
+export type InternalJwtPayload = HumanInternalJwtPayload | MachineInternalJwtPayload;
+export interface HumanAccessContext {
+    kind: "human";
+    accountId: string;
+    accountRole: AccountRole;
+    /**
+     * Resolved from Redis permission cache — NOT from the JWT.
+     * Always present by the time req.accessContext is set.
+     * Invalidated on role change, suspension, and account deletion.
+     */
+    perms: GlobalPermission[];
+}
+export interface MachineAccessContext {
+    kind: "machine";
+    serviceId: string;
+}
+export type AccessContext = HumanAccessContext | MachineAccessContext;
+export declare function isHumanPayload(payload: InternalJwtPayload): payload is HumanInternalJwtPayload;
+export declare function isMachinePayload(payload: InternalJwtPayload): payload is MachineInternalJwtPayload;
+export declare function isHumanContext(ctx: AccessContext): ctx is HumanAccessContext;
+export declare function isMachineContext(ctx: AccessContext): ctx is MachineAccessContext;
+export interface VerifiedAccessPayload {
+    accountId: string;
+    accountRole: AccountRole;
+    typ: "access";
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf: number;
+    jti: string;
+}
+export interface VerifiedRefreshPayload {
+    accountId: string;
+    typ: "refresh";
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf: number;
+    jti: string;
+}
+declare module "express-serve-static-core" {
+    interface Request {
+        /**
+         * Unique request ID — set by requestId middleware.
+         * Respects upstream x-request-id from the gateway / load balancer.
+         * Always present after requestId middleware runs.
+         */
+        id: string;
+        /**
+         * Validated + parsed request body/query/params/headers.
+         * Typed as unknown — narrow at the route level:
+         *
+         *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+         *
+         * Never cast to any.
+         */
+        validated?: unknown;
+        /**
+         * Raw verified internal JWT payload.
+         * Set by RequireAuthMiddleware after InternalJwtVerifier.verifyInternal().
+         *
+         * Prefer req.accessContext in route handlers.
+         * Access this only when you need raw JWT claims (e.g. jti for blacklisting).
+         */
+        internalAuth?: InternalJwtPayload;
+        /**
+         * Clean access context — built from internalAuth + permission cache.
+         * This is what route handlers, controllers, and domain services use.
+         *
+         *   if (isHumanContext(req.accessContext)) {
+         *     const { accountId, accountRole, perms } = req.accessContext;
+         *   }
+         */
+        accessContext?: AccessContext;
+    }
+}
+export {};

package/dist/types/express.types.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
+ * ───────────────────────────────────────────────
+ * Single source of truth for everything attached to Express's Request object
+ * and all internal JWT payload shapes.
+ *
+ * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ *   import "@discover-cloud/shared/types/express";
+ *
+ * ─── Permission flow ────────────────────────────────────────────────
+ *   JWT carries:        accountId + accountRole   (lean, no perms)
+ *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
+ *   AccessContext has:  perms                      (populated by auth middleware)
+ *
+ *   perms never touch the JWT — they live in the permission cache and are
+ *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHumanPayload = isHumanPayload;
+exports.isMachinePayload = isMachinePayload;
+exports.isHumanContext = isHumanContext;
+exports.isMachineContext = isMachineContext;
+require("express-serve-static-core");
+/* ====================================================================
+   4. TYPE GUARDS
+
+   Use these over raw property checks — TypeScript narrows correctly
+   through them on both InternalJwtPayload and AccessContext.
+==================================================================== */
+function isHumanPayload(payload) {
+    return payload.isMachine === false;
+}
+function isMachinePayload(payload) {
+    return payload.isMachine === true;
+}
+function isHumanContext(ctx) {
+    return ctx.kind === "human";
+}
+function isMachineContext(ctx) {
+    return ctx.kind === "machine";
+}

package/dist/types/index.d.ts

@@ -1 +1 @@
-export * from "./express";
+export * from "./express.types";

package/dist/types/index.js

@@ -14,4 +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("./express"), exports);
+__exportStar(require("./express.types"), exports);

package/dist/utils/index.d.ts

@@ -1 +1,2 @@
-export * from "./response";
+export * from "./response.utils";
+export * from "./logger.utils";

package/dist/utils/index.js

@@ -14,4 +14,5 @@ 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("./response"), exports);
+__exportStar(require("./response.utils"), exports);
+__exportStar(require("./logger.utils"), exports);

package/dist/utils/logger.utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LOGGER INTERFACE  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
+ * A minimal logger contract shared code can depend on.
+ * Each service injects its own implementation (pino, winston, console).
+ *
+ * Shared code (RequireAuthMiddleware, PermissionCacheService, etc.)
+ * accepts this interface — it never imports a concrete logger directly.
+ *
+ * ─── Usage in shared classes ────────────────────────────────────────
+ *   class RequireAuthMiddleware {
+ *     constructor(
+ *       private readonly verifier: InternalJwtVerifier,
+ *       private readonly logger:   ILogger = noopLogger,
+ *     ) {}
+ *   }
+ *
+ * ─── Wiring in each service ─────────────────────────────────────────
+ *   // auth-service / composition root:
+ *   import pino from "pino";
+ *   const pinoLogger = pino({ level: "info" });
+ *
+ *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, pinoLogger);
+ *
+ * ─── noopLogger ─────────────────────────────────────────────────────
+ *   The default when no logger is injected — silently drops all logs.
+ *   Safe for tests and library consumers that don't want log noise.
+ */
+export interface ILogger {
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+}
+/**
+ * noopLogger
+ * Silent default — used when no logger is injected.
+ * Satisfies ILogger without importing any logging library.
+ */
+export declare const noopLogger: ILogger;
+/**
+ * consoleLogger
+ * Thin console wrapper — useful for local dev and simple services
+ * that don't need structured logging.
+ * Pass this when you want logs without wiring up pino/winston.
+ */
+export declare const consoleLogger: ILogger;

package/dist/utils/logger.utils.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * LOGGER INTERFACE  (@discover-cloud/shared)
+ * ────────────────────────────────────────────
+ * A minimal logger contract shared code can depend on.
+ * Each service injects its own implementation (pino, winston, console).
+ *
+ * Shared code (RequireAuthMiddleware, PermissionCacheService, etc.)
+ * accepts this interface — it never imports a concrete logger directly.
+ *
+ * ─── Usage in shared classes ────────────────────────────────────────
+ *   class RequireAuthMiddleware {
+ *     constructor(
+ *       private readonly verifier: InternalJwtVerifier,
+ *       private readonly logger:   ILogger = noopLogger,
+ *     ) {}
+ *   }
+ *
+ * ─── Wiring in each service ─────────────────────────────────────────
+ *   // auth-service / composition root:
+ *   import pino from "pino";
+ *   const pinoLogger = pino({ level: "info" });
+ *
+ *   const requireAuth = new RequireAuthMiddleware(jwtVerifier, pinoLogger);
+ *
+ * ─── noopLogger ─────────────────────────────────────────────────────
+ *   The default when no logger is injected — silently drops all logs.
+ *   Safe for tests and library consumers that don't want log noise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consoleLogger = exports.noopLogger = void 0;
+/**
+ * noopLogger
+ * Silent default — used when no logger is injected.
+ * Satisfies ILogger without importing any logging library.
+ */
+exports.noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * consoleLogger
+ * Thin console wrapper — useful for local dev and simple services
+ * that don't need structured logging.
+ * Pass this when you want logs without wiring up pino/winston.
+ */
+exports.consoleLogger = {
+    debug: (objOrMsg, msg) => {
+        console.debug(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+    },
+    info: (objOrMsg, msg) => {
+        console.info(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+    },
+    warn: (objOrMsg, msg) => {
+        console.warn(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+    },
+    error: (objOrMsg, msg) => {
+        console.error(msg ?? objOrMsg, typeof objOrMsg === "object" ? objOrMsg : "");
+    },
+};

package/dist/utils/response.d.ts

@@ -1,3 +1,4 @@
 import { Response } from "express";
 export declare const success: <T>(res: Response, data: T, statusCode?: number) => Response<any, Record<string, any>>;
-export declare const failure: (res: Response, message: string, statusCode?: number, details?: unknown) => Response<any, Record<string, any>>;
+export declare const failure: (res: Response, message: string, code: string, // <-- Added to match the DTO requirement
+statusCode?: number, details?: unknown) => Response<any, Record<string, any>>;

package/dist/utils/response.js

@@ -2,28 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.failure = exports.success = void 0;
 const success = (res, data, statusCode = 200) => {
+    // Cast to Request to access properties safely, assuming module augmentation
     const req = res.req;
     const response = {
         success: true,
         data,
         meta: {
-            requestId: req?.id ?? null,
+            requestId: req.id ?? "unknown", // Fallback if middleware failed
             timestamp: new Date().toISOString()
         }
     };
     return res.status(statusCode).json(response);
 };
 exports.success = success;
-const failure = (res, message, statusCode = 400, details) => {
+const failure = (res, message, code, // <-- Added to match the DTO requirement
+statusCode = 400, details) => {
     const req = res.req;
     const response = {
         success: false,
         error: {
+            code, // <-- Added here
             message,
             details: details ?? null
         },
         meta: {
-            requestId: req?.id ?? null,
+            requestId: req.id ?? "unknown",
             timestamp: new Date().toISOString()
         }
     };

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

@@ -0,0 +1,12 @@
+import { Response, Request } from "express";
+/**
+ * RESPONSE HELPERS
+ * ─────────────────
+ * Typed wrappers around res.json() that enforce the ApiSuccessResponse
+ * and ApiErrorResponse envelope shapes.
+ *
+ * Both require req explicitly — avoids the res.req cast anti-pattern
+ * and makes the dependency clear at the call site.
+ */
+export declare const success: <T>(res: Response, req: Request, data: T, statusCode?: number) => void;
+export declare const failure: (res: Response, req: Request, message: string, code: string, statusCode?: number, details?: unknown) => void;

package/dist/utils/response.utils.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failure = exports.success = void 0;
+const crypto_1 = require("crypto");
+/**
+ * RESPONSE HELPERS
+ * ─────────────────
+ * Typed wrappers around res.json() that enforce the ApiSuccessResponse
+ * and ApiErrorResponse envelope shapes.
+ *
+ * Both require req explicitly — avoids the res.req cast anti-pattern
+ * and makes the dependency clear at the call site.
+ */
+const success = (res, req, data, statusCode = 200) => {
+    const response = {
+        success: true,
+        data,
+        meta: {
+            requestId: req.id ?? (0, crypto_1.randomUUID)(), // randomUUID fallback — "unknown" breaks log search
+            timestamp: new Date().toISOString(),
+        },
+    };
+    res.status(statusCode).json(response);
+};
+exports.success = success;
+const failure = (res, req, message, code, statusCode = 400, details) => {
+    const response = {
+        success: false,
+        error: {
+            code,
+            message,
+            // Omit details entirely when not provided — avoids "details": null noise
+            ...(details !== undefined ? { details } : {}),
+        },
+        meta: {
+            requestId: req.id ?? (0, crypto_1.randomUUID)(),
+            timestamp: new Date().toISOString(),
+        },
+    };
+    res.status(statusCode).json(response);
+};
+exports.failure = failure;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discover-cloud/shared",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "type": "commonjs",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "axios-retry": "^4.5.0",
-    "jose": "^6.1.3"
+    "jose": "^6.1.3",
+    "redis": "^5.11.0"
   },
   "peerDependencies": {
     "axios": "^1.13.5",