@discover-cloud/shared 1.2.3 → 1.2.5

package/dist/middleware/index.d.ts

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

package/dist/middleware/index.js

@@ -20,3 +20,5 @@ __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);
+__exportStar(require("./require-human.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 requireAuth {
+    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.requireAuth = 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 requireAuth {
+    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.requireAuth = requireAuth;

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

@@ -0,0 +1,2 @@
+import { Request, Response, NextFunction } from "express";
+export declare const requireHuman: (req: Request, res: Response, next: NextFunction) => void;

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireHuman = void 0;
+const utils_1 = require("../utils");
+const types_1 = require("../types");
+const requireHuman = (req, res, next) => {
+    const ctx = req.accessContext;
+    if (!ctx) {
+        (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+        return;
+    }
+    if (!(0, types_1.isHumanContext)(ctx)) {
+        (0, utils_1.failure)(res, req, "Human token required", "FORBIDDEN", 403);
+        return;
+    }
+    next();
+};
+exports.requireHuman = requireHuman;

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requireInternal = requireInternal;
 const jose = __importStar(require("jose"));
+const types_1 = require("../types");
 const logger_utils_1 = require("../utils/logger.utils");
 /**
  * REQUIRE INTERNAL MIDDLEWARE  (@discover-cloud/shared)
@@ -125,14 +126,20 @@ function requireInternal(options = {}) {
                 });
                 return;
             }
-            const serviceId = payload["serviceId"];
-            if (typeof serviceId !== "string") {
+            try {
+                (0, types_1.assertMachinePayload)(payload);
+            }
+            catch {
                 res.status(401).json({
                     success: false,
-                    error: { code: "INVALID_TOKEN", message: "Token missing serviceId" },
+                    error: {
+                        code: "INVALID_TOKEN",
+                        message: "Invalid machine token payload",
+                    },
                 });
                 return;
             }
+            const serviceId = payload.serviceId;
             // Allowlist — tightest possible scope per endpoint
             if (allowedServices && !allowedServices.includes(serviceId)) {
                 logger.warn({ requestId: req.id, serviceId }, "[requireInternal] serviceId not in allowlist");
@@ -143,6 +150,7 @@ function requireInternal(options = {}) {
                 return;
             }
             const context = { kind: "machine", serviceId };
+            req.internalAuth = payload;
             req.accessContext = context;
             logger.debug({ requestId: req.id, serviceId, jti: payload.jti }, "[requireInternal] Machine token verified");
             next();

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

@@ -96,6 +96,14 @@ export interface MachineAccessContext {
 export type AccessContext = HumanAccessContext | MachineAccessContext;
 export declare function isHumanPayload(payload: InternalJwtPayload): payload is HumanInternalJwtPayload;
 export declare function isMachinePayload(payload: InternalJwtPayload): payload is MachineInternalJwtPayload;
+/**
+ * Runtime assertion for jose.jwtVerify() results.
+ *
+ * jose returns a generic JWTPayload because it cannot know
+ * our custom claims. After verification + this assertion,
+ * TypeScript safely treats it as MachineInternalJwtPayload.
+ */
+export declare function assertMachinePayload(payload: JWTPayload): asserts payload is MachineInternalJwtPayload;
 export declare function isHumanContext(ctx: AccessContext): ctx is HumanAccessContext;
 export declare function isMachineContext(ctx: AccessContext): ctx is MachineAccessContext;
 export interface VerifiedAccessPayload {

package/dist/types/express.types.js

@@ -20,6 +20,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isHumanPayload = isHumanPayload;
 exports.isMachinePayload = isMachinePayload;
+exports.assertMachinePayload = assertMachinePayload;
 exports.isHumanContext = isHumanContext;
 exports.isMachineContext = isMachineContext;
 /* ====================================================================
@@ -35,6 +36,22 @@ function isHumanPayload(payload) {
 function isMachinePayload(payload) {
     return payload.isMachine === true;
 }
+/**
+ * Runtime assertion for jose.jwtVerify() results.
+ *
+ * jose returns a generic JWTPayload because it cannot know
+ * our custom claims. After verification + this assertion,
+ * TypeScript safely treats it as MachineInternalJwtPayload.
+ */
+function assertMachinePayload(payload) {
+    if (payload["typ"] !== "internal" ||
+        payload["isMachine"] !== true ||
+        typeof payload["serviceId"] !== "string" ||
+        typeof payload["jti"] !== "string" ||
+        typeof payload["caller"] !== "string") {
+        throw new Error("Invalid machine JWT payload");
+    }
+}
 function isHumanContext(ctx) {
     return ctx.kind === "human";
 }

package/package.json

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