@discover-cloud/shared 1.0.0 → 1.0.1

package/dist/index.d.ts

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

package/dist/index.js

@@ -17,8 +17,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./enums"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./dto"), exports);
-__exportStar(require("./security"), 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,23 @@
+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 (BadRequestError, NotFoundError, etc.)
+ *   3. Unknown         → 500 Internal Server Error
+ *
+ * Every response includes requestId for traceability.
+ *
+ * Fix vs original:
+ *   - Replaced unsafe duck-type cast `(err as { statusCode? })` with
+ *     proper `instanceof AppError` check. Duck-typing any error with a
+ *     statusCode property as an AppError is a bug vector.
+ *   - req.id included in every error response
+ *   - Stack trace logged only in non-production environments
+ */
+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,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GlobalErrorHandler = void 0;
+const zod_1 = require("zod");
+const app_error_1 = require("../errors/app-error");
+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 (BadRequestError, NotFoundError, etc.)
+ *   3. Unknown         → 500 Internal Server Error
+ *
+ * Every response includes requestId for traceability.
+ *
+ * Fix vs original:
+ *   - Replaced unsafe duck-type cast `(err as { statusCode? })` with
+ *     proper `instanceof AppError` check. Duck-typing any error with a
+ *     statusCode property as an AppError is a bug vector.
+ *   - req.id included in every error response
+ *   - Stack trace logged only in non-production environments
+ */
+class GlobalErrorHandler {
+    static handle(err, req, res, _next) {
+        const requestId = req.id;
+        // Always log — replace with your pino/winston logger in production
+        if (process.env.NODE_ENV !== "production") {
+            console.error(`[req ${requestId}]`, err);
+        }
+        else {
+            // In production, log without the stack trace in the response
+            console.error(`[req ${requestId}]`, err instanceof Error ? err.message : err);
+        }
+        // 1. Zod validation errors
+        if (err instanceof zod_1.ZodError) {
+            (0, utils_1.failure)(res, "Validation failed", "VALIDATION_ERROR", 400, err.flatten((issue) => issue.message));
+            return;
+        }
+        // 2. Known AppError subclasses (BadRequestError, NotFoundError, etc.)
+        //    instanceof check — safe, no duck-typing
+        if (err instanceof app_error_1.AppError) {
+            (0, utils_1.failure)(res, err.message, err.code, err.statusCode, err.details);
+            return;
+        }
+        // 3. Unhandled / unexpected errors — never leak internals
+        (0, utils_1.failure)(res, "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;

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;