@discover-cloud/shared 1.2.3 → 1.2.4

package/dist/middleware/index.d.ts

@@ -4,3 +4,4 @@ export * from "./request-id.middleware";
 export * from "./authorize.middleware";
 export * from "./validated-merge.middleware";
 export * from "./require-internal.middleware";
+export * from "./require-auth.middleware";

package/dist/middleware/index.js

@@ -20,3 +20,4 @@ __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("./require-auth.middleware"), exports);

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

@@ -0,0 +1,86 @@
+import { Request, Response, NextFunction } from "express";
+import { AccountRole } from "../enums";
+import { GlobalPermission } from "../enums";
+import { ILogger } from "../utils";
+import { InternalJwtVerifier } from "../jwt/internal-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);
+ */
+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)
+     */
+    handle: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+    /**
+     * Inline permission guard — use when this class instance is available at the call site.
+     * For router-level guards, prefer requireGlobalPermission() from permission.middleware.ts.
+     *
+     * 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.
+     */
+    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;
+}

package/dist/middleware/require-auth.middleware.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireAuthMiddleware = void 0;
+const jose_1 = require("jose");
+const utils_1 = require("../utils");
+const internal_jwt_verifier_1 = require("../jwt/internal-jwt-verifier");
+const utils_2 = require("../utils");
+/**
+ * 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);
+ */
+class RequireAuthMiddleware {
+    constructor(verifier, logger = utils_1.noopLogger) {
+        this.verifier = verifier;
+        this.logger = logger;
+        /**
+         * Core authentication middleware.
+         * Apply via: router.use(requireAuth.handle) or router.get("/", requireAuth.handle, controller.x)
+         */
+        this.handle = async (req, res, next) => {
+            const token = this.extractBearer(req);
+            if (!token) {
+                (0, utils_2.failure)(res, req, "Missing Authorization header", "UNAUTHORIZED", 401);
+                return;
+            }
+            try {
+                const { payload, context } = await this.verifier.buildAccessContext(token);
+                req.internalAuth = payload;
+                req.accessContext = context;
+                this.logger.debug({
+                    requestId: req.id,
+                    // log accountId for humans, serviceId for machines — never log both
+                    identity: context.kind === "human" ? context.accountId : context.serviceId,
+                    kind: context.kind,
+                    caller: payload.caller,
+                }, "Request authenticated");
+                next();
+            }
+            catch (err) {
+                this.handleJwtError(err, req, res);
+            }
+        };
+        /**
+         * Inline permission guard — use when this class instance is available at the call site.
+         * For router-level guards, prefer requireGlobalPermission() from permission.middleware.ts.
+         *
+         * Usage: router.get("/", requireAuth.handle, requireAuth.requirePermission(P.READ_ACCOUNTS), controller.list)
+         */
+        this.requirePermission = (permission) => (req, res, next) => {
+            const ctx = req.accessContext;
+            if (!ctx) {
+                // Should not happen after handle() — indicates middleware ordering bug
+                (0, utils_2.failure)(res, req, "No access context — ensure requireAuth runs first", "UNAUTHORIZED", 401);
+                return;
+            }
+            if (!internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(ctx, permission)) {
+                (0, utils_2.failure)(res, req, `Missing required permission: ${permission}`, "FORBIDDEN", 403);
+                return;
+            }
+            next();
+        };
+        /**
+         * 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").
+         */
+        this.requireRole = (role) => (req, res, next) => {
+            const ctx = req.accessContext;
+            if (!ctx) {
+                (0, utils_2.failure)(res, req, "No access context — ensure requireAuth runs first", "UNAUTHORIZED", 401);
+                return;
+            }
+            if (!internal_jwt_verifier_1.InternalJwtVerifier.hasRole(ctx, role)) {
+                (0, utils_2.failure)(res, req, `Missing required role: ${role}`, "FORBIDDEN", 403);
+                return;
+            }
+            next();
+        };
+    }
+    /* ────────────────────────────────────────────────────────────────────
+       PRIVATE HELPERS
+    ──────────────────────────────────────────────────────────────────── */
+    /**
+     * 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.
+     */
+    extractBearer(req) {
+        const header = req.headers.authorization;
+        if (!header) {
+            return null;
+        }
+        const [scheme, token] = header.trim().split(/\s+/);
+        if (scheme !== "Bearer" || !token) {
+            return null;
+        }
+        return token;
+    }
+    /**
+     * 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.
+     */
+    handleJwtError(err, req, res) {
+        if (err instanceof jose_1.errors.JWTExpired) {
+            (0, utils_2.failure)(res, req, "Your session has expired. Please log in again.", "TOKEN_EXPIRED", 401);
+            return;
+        }
+        if (err instanceof jose_1.errors.JWTClaimValidationFailed ||
+            err instanceof jose_1.errors.JWSSignatureVerificationFailed ||
+            err instanceof jose_1.errors.JWSInvalid ||
+            err instanceof jose_1.errors.JWTInvalid) {
+            (0, utils_2.failure)(res, req, "Token is invalid or has been tampered with.", "INVALID_TOKEN", 401);
+            return;
+        }
+        // Unexpected error — log for investigation, return a safe 503
+        this.logger.error({ err, requestId: req.id }, "RequireAuthMiddleware: unexpected error during JWT verification");
+        (0, utils_2.failure)(res, req, "Authentication service is temporarily unavailable.", "SERVICE_UNAVAILABLE", 503);
+    }
+}
+exports.RequireAuthMiddleware = RequireAuthMiddleware;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discover-cloud/shared",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "private": false,
   "type": "commonjs",
   "main": "dist/index.js",