@discover-cloud/shared 1.2.9 → 1.4.0

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

@@ -1,85 +1,16 @@
-import { Request, Response, NextFunction } from "express";
-import { AccountRole, 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);
+ * @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 { ILogger } from '../utils';
+import { UserJwtVerifier } from '../jwt/user-jwt-verifier';
 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)
-     */
+    constructor(verifier: UserJwtVerifier, logger?: ILogger);
     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

@@ -1,162 +1,74 @@
 "use strict";
+/**
+ * @file require-auth.middleware.ts
+ * @description Authentication boundary middleware. Verifies the internal gateway JWT,
+ * builds the auth context, and gates endpoints.
+ */
 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");
-/**
- * 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);
- */
+const request_context_storage_1 = require("../context/request-context.storage");
 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_1.failure)(res, req, "Missing Authorization header", "UNAUTHORIZED", 401);
+                (0, utils_1.failure)(res, req, 'Missing Authorization header', 'UNAUTHORIZED', 401);
                 return;
             }
             try {
                 const { payload, context } = await this.verifier.buildAccessContext(token);
-                req.internalAuth = payload;
-                req.accessContext = context;
+                req.authPayload = payload;
+                req.authContext = context;
+                // Attach audit context. Will throw if requestContextStorage is not initialized.
+                request_context_storage_1.RequestContextProvider.setActor(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");
+                    identity: context.accountId,
+                    type: context.type,
+                }, '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_1.failure)(res, req, "No access context — ensure requireAuth runs first", "UNAUTHORIZED", 401);
-                return;
-            }
-            if (!internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(ctx, permission)) {
-                (0, utils_1.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_1.failure)(res, req, "No access context — ensure requireAuth runs first", "UNAUTHORIZED", 401);
-                return;
-            }
-            if (!internal_jwt_verifier_1.InternalJwtVerifier.hasRole(ctx, role)) {
-                (0, utils_1.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.
-     */
+    /* ---------------------------------------------------------------------------
+       Private Helpers
+    --------------------------------------------------------------------------- */
     extractBearer(req) {
         const header = req.headers.authorization;
-        if (!header) {
+        if (!header)
             return null;
-        }
         const [scheme, token] = header.trim().split(/\s+/);
-        if (scheme !== "Bearer" || !token) {
+        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_1.failure)(res, req, "Your session has expired. Please log in again.", "TOKEN_EXPIRED", 401);
+            (0, utils_1.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_1.failure)(res, req, "Token is invalid or has been tampered with.", "INVALID_TOKEN", 401);
+            (0, utils_1.failure)(res, req, 'Token is invalid or has been tampered with.', 'INVALID_TOKEN', 401);
+            return;
+        }
+        // Catch the specific Developer Error from RequestContextProvider
+        if (err instanceof Error && err.message.includes('AuditRequestContext')) {
+            this.logger.error({ err, requestId: req.id }, 'CRITICAL: RequireAuthMiddleware failed because requestContextStorage is not initialized. Check your middleware order.');
+            (0, utils_1.failure)(res, req, 'Internal server configuration error.', 'INTERNAL_SERVER_ERROR', 500);
             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_1.failure)(res, req, "Authentication service is temporarily unavailable.", "SERVICE_UNAVAILABLE", 503);
+        this.logger.error({ err, requestId: req.id }, 'RequireAuthMiddleware: unexpected error during JWT verification');
+        (0, utils_1.failure)(res, req, 'Authentication service is temporarily unavailable.', 'SERVICE_UNAVAILABLE', 503);
     }
 }
 exports.RequireAuthMiddleware = RequireAuthMiddleware;

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

@@ -0,0 +1,13 @@
+/**
+ * @file require-machine.middleware.ts
+ * @description Express middleware enforcing auth-service issued machine JWT verification
+ * for service-to-service communication endpoints.
+ */
+import { RequestHandler } from 'express';
+import { ILogger } from '../utils/logger.util';
+export interface RequireMachineOptions {
+    authServiceJwksUri?: string;
+    allowedServices?: string[];
+    logger?: ILogger;
+}
+export declare function requireMachine(options?: RequireMachineOptions): RequestHandler;

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

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * @file require-machine.middleware.ts
+ * @description Express middleware enforcing auth-service issued machine JWT verification
+ * for service-to-service communication endpoints.
+ */
+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.requireMachine = requireMachine;
+const jose = __importStar(require("jose"));
+const logger_util_1 = require("../utils/logger.util");
+const machine_jwt_verifier_1 = require("../jwt/machine-jwt-verifier");
+const request_context_storage_1 = require("../context/request-context.storage");
+function requireMachine(options = {}) {
+    const logger = options.logger ?? logger_util_1.noopLogger;
+    const verifier = new machine_jwt_verifier_1.MachineJwtVerifier(options.authServiceJwksUri);
+    const { allowedServices } = options;
+    return async (req, res, next) => {
+        const header = req.headers.authorization;
+        if (!header?.startsWith('Bearer ')) {
+            res.status(401).json({
+                success: false,
+                error: {
+                    code: 'UNAUTHORIZED',
+                    message: 'Missing Authorization header',
+                },
+            });
+            return;
+        }
+        const token = header.slice(7);
+        try {
+            const payload = await verifier.verify(token);
+            if (allowedServices && !allowedServices.includes(payload.serviceId)) {
+                logger.warn({ requestId: req.id, serviceId: payload.serviceId }, '[requireMachine] Service rejected');
+                res.status(403).json({
+                    success: false,
+                    error: {
+                        code: 'FORBIDDEN',
+                        message: 'Service is not permitted to access this endpoint',
+                    },
+                });
+                return;
+            }
+            const context = {
+                type: 'machine',
+                serviceId: payload.serviceId,
+                scopes: payload.scopes,
+            };
+            req.authPayload = payload;
+            req.authContext = context;
+            // Attach audit context. Will throw if requestContextStorage is not initialized.
+            request_context_storage_1.RequestContextProvider.setActor(context);
+            logger.debug({ requestId: req.id, serviceId: payload.serviceId, jti: payload.jti }, '[requireMachine] Machine authenticated');
+            next();
+        }
+        catch (err) {
+            if (err instanceof jose.errors.JWTExpired) {
+                res.status(401).json({
+                    success: false,
+                    error: { code: 'TOKEN_EXPIRED', message: 'Machine token expired' },
+                });
+                return;
+            }
+            if (err instanceof jose.errors.JWTClaimValidationFailed ||
+                err instanceof jose.errors.JWSSignatureVerificationFailed ||
+                err instanceof jose.errors.JWSInvalid ||
+                err instanceof jose.errors.JWTInvalid) {
+                res.status(401).json({
+                    success: false,
+                    error: { code: 'INVALID_TOKEN', message: 'Invalid machine token' },
+                });
+                return;
+            }
+            // Catch the specific Developer Error from RequestContextProvider
+            if (err instanceof Error && err.message.includes('AuditRequestContext')) {
+                logger.error({ err, requestId: req.id }, 'CRITICAL: [requireMachine] failed because requestContextStorage is not initialized. Check middleware order.');
+                res.status(500).json({
+                    success: false,
+                    error: {
+                        code: 'INTERNAL_SERVER_ERROR',
+                        message: 'Internal server configuration error',
+                    },
+                });
+                return;
+            }
+            logger.error({ err, requestId: req.id }, '[requireMachine] Machine authentication failure');
+            res.status(503).json({
+                success: false,
+                error: {
+                    code: 'SERVICE_UNAVAILABLE',
+                    message: 'Machine authentication temporarily unavailable',
+                },
+            });
+        }
+    };
+}

package/dist/middleware/require-org-permission-from-body.middleware.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file require-org-permission-from-body.middleware.ts
+ * @description Checks org permission only when organizationId exists in request body.
+ * Used for endpoints that support both personal and organization scopes.
+ */
+import { RequestHandler } from 'express';
+import { Permission } from '../enums';
+export declare const createRequireOrgPermissionFromBody: (requireOrgPermission: (permission: Permission) => RequestHandler) => {
+    requireOrgPermissionFromBody: (permission: Permission) => RequestHandler;
+};

package/dist/middleware/require-org-permission-from-body.middleware.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @file require-org-permission-from-body.middleware.ts
+ * @description Checks org permission only when organizationId exists in request body.
+ * Used for endpoints that support both personal and organization scopes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireOrgPermissionFromBody = void 0;
+const createRequireOrgPermissionFromBody = (requireOrgPermission) => {
+    const requireOrgPermissionFromBody = (permission) => {
+        return async (req, res, next) => {
+            const organizationId = req.body?.organizationId ?? req.validated?.body?.organizationId;
+            if (!organizationId) {
+                return next();
+            }
+            return requireOrgPermission(permission)(req, res, next);
+        };
+    };
+    return {
+        requireOrgPermissionFromBody,
+    };
+};
+exports.createRequireOrgPermissionFromBody = createRequireOrgPermissionFromBody;

package/dist/middleware/require-org-permission.middleware.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file require-org-permission.middleware.ts
+ * @description Express middleware generator to enforce organization-scoped permission checks.
+ */
+import { RequestHandler } from 'express';
+import { Permission } from '../enums';
+import { PermissionCacheService } from '../authorization/permission-cache.service';
+/**
+ * Creates requireOrgPermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, organizationId: string) => Promise<string[]>} resolveFn - Cache miss database/API lookup function.
+ * @returns {object} Organization permission middlewares.
+ */
+export declare const createRequireOrgPermission: (permissionCache: PermissionCacheService, resolveFn: (accountId: string, organizationId: string) => Promise<string[]>) => {
+    requireOrgPermission: (permission: Permission) => RequestHandler;
+    requireAnyOrgPermission: (...permissions: Permission[]) => RequestHandler;
+    requireAllOrgPermissions: (...permissions: Permission[]) => RequestHandler;
+};

package/dist/middleware/require-org-permission.middleware.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * @file require-org-permission.middleware.ts
+ * @description Express middleware generator to enforce organization-scoped permission checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireOrgPermission = void 0;
+const permission_checker_1 = require("../authorization/permission-checker");
+const utils_1 = require("../utils");
+/**
+ * Creates requireOrgPermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, organizationId: string) => Promise<string[]>} resolveFn - Cache miss database/API lookup function.
+ * @returns {object} Organization permission middlewares.
+ */
+const createRequireOrgPermission = (permissionCache, resolveFn) => {
+    const requireOrgPermission = (permission) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== 'user') {
+                (0, utils_1.failure)(res, req, 'Unauthorized: No auth context', 'UNAUTHORIZED', 401);
+                return;
+            }
+            const organizationId = req.params['organizationId'] ??
+                req.params['orgId'] ??
+                req.validated?.params?.['organizationId'] ??
+                req.validated?.body?.['organizationId'];
+            if (!organizationId || typeof organizationId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing organization context', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveOrganizationPermissions(ctx.accountId, organizationId, async () => {
+                    return resolveFn(ctx.accountId, organizationId);
+                });
+                if (!permission_checker_1.PermissionChecker.has(perms, permission)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required organization permission: ${permission}`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAnyOrgPermission = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== 'user') {
+                (0, utils_1.failure)(res, req, 'Unauthorized: No auth context', 'UNAUTHORIZED', 401);
+                return;
+            }
+            const organizationId = req.params['organizationId'] ??
+                req.params['orgId'] ??
+                req.validated?.params?.['organizationId'] ??
+                req.validated?.body?.['organizationId'];
+            if (!organizationId || typeof organizationId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing organization context', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveOrganizationPermissions(ctx.accountId, organizationId, async () => {
+                    return resolveFn(ctx.accountId, organizationId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAny(perms, permissions)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing one of required organization permissions: [${permissions.join(', ')}]`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAllOrgPermissions = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== 'user') {
+                (0, utils_1.failure)(res, req, 'Unauthorized: No auth context', 'UNAUTHORIZED', 401);
+                return;
+            }
+            const organizationId = req.params['organizationId'] ??
+                req.params['orgId'] ??
+                req.validated?.params?.['organizationId'] ??
+                req.validated?.body?.['organizationId'];
+            if (!organizationId || typeof organizationId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing organization context', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveOrganizationPermissions(ctx.accountId, organizationId, async () => {
+                    return resolveFn(ctx.accountId, organizationId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAll(perms, permissions)) {
+                    const missing = permissions.filter((p) => !permission_checker_1.PermissionChecker.has(perms, p));
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required organization permissions: [${missing.join(', ')}]`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    return {
+        requireOrgPermission,
+        requireAnyOrgPermission,
+        requireAllOrgPermissions,
+    };
+};
+exports.createRequireOrgPermission = createRequireOrgPermission;

package/dist/middleware/require-platform-permission.middleware.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file require-platform-permission.middleware.ts
+ * @description Express middleware generator to enforce platform-scoped permission checks.
+ */
+import { RequestHandler } from 'express';
+import { PlatformPermission } from '../enums';
+import { PermissionCacheService } from '../authorization/permission-cache.service';
+/**
+ * Creates requirePlatformPermission middleware.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string) => Promise<string[]>} resolveFn - Cache miss database/API lookup function.
+ * @returns {object} Platform permission middlewares.
+ */
+export declare const createRequirePlatformPermission: (permissionCache: PermissionCacheService, resolveFn: (accountId: string) => Promise<string[]>) => {
+    requirePlatformPermission: (permission: PlatformPermission) => RequestHandler;
+    requireAnyPlatformPermission: (...permissions: PlatformPermission[]) => RequestHandler;
+    requireAllPlatformPermissions: (...permissions: PlatformPermission[]) => RequestHandler;
+};