@discover-cloud/shared 1.2.8 → 1.3.0

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

@@ -1,53 +1,32 @@
 "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);
+ * Middleware handling authentication validation.
+ * Extracts the JWT, verifies it via UserJwtVerifier, and attaches the AuthContext.
  */
 class RequireAuthMiddleware {
+    /**
+     * @param {UserJwtVerifier} verifier - The token verification engine.
+     * @param {ILogger}             [logger] - Optional logger instance.
+     */
     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)
+         * Core Express middleware handler for authenticating requests.
+         *
+         * @param {Request}      req  - Express request object.
+         * @param {Response}     res  - Express response object.
+         * @param {NextFunction} next - Express next function.
+         * @returns {Promise<void>}
          */
         this.handle = async (req, res, next) => {
             const token = this.extractBearer(req);
@@ -57,14 +36,12 @@ class RequireAuthMiddleware {
             }
             try {
                 const { payload, context } = await this.verifier.buildAccessContext(token);
-                req.internalAuth = payload;
-                req.accessContext = context;
+                req.authPayload = payload;
+                req.authContext = 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,
+                    identity: context.accountId,
+                    type: context.type,
                 }, "Request authenticated");
                 next();
             }
@@ -72,52 +49,10 @@ class RequireAuthMiddleware {
                 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) {
@@ -129,19 +64,6 @@ class RequireAuthMiddleware {
         }
         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);
@@ -154,7 +76,6 @@ class RequireAuthMiddleware {
             (0, utils_1.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_1.failure)(res, req, "Authentication service is temporarily unavailable.", "SERVICE_UNAVAILABLE", 503);
     }

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

@@ -0,0 +1,38 @@
+/**
+ * @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";
+/**
+ * Configuration options for machine authentication middleware.
+ */
+export interface RequireMachineOptions {
+    /**
+     * Auth-service JWKS endpoint used to verify machine JWT signatures.
+     */
+    authServiceJwksUri?: string;
+    /**
+     * Service identifiers allowed to access this endpoint.
+     */
+    allowedServices?: string[];
+    /**
+     * Optional structured logger.
+     */
+    logger?: ILogger;
+}
+/**
+ * Creates middleware requiring a valid machine JWT.
+ *
+ * Flow:
+ * - Extract Bearer token
+ * - Verify RS256 signature using auth-service JWKS
+ * - Validate machine token claims
+ * - Apply service allowlist
+ * - Attach MachineContext
+ *
+ * @param {RequireMachineOptions} [options] - Middleware configuration options.
+ * @returns {RequestHandler} Express middleware handler.
+ */
+export declare function requireMachine(options?: RequireMachineOptions): RequestHandler;

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

@@ -0,0 +1,123 @@
+"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");
+/**
+ * Creates middleware requiring a valid machine JWT.
+ *
+ * Flow:
+ * - Extract Bearer token
+ * - Verify RS256 signature using auth-service JWKS
+ * - Validate machine token claims
+ * - Apply service allowlist
+ * - Attach MachineContext
+ *
+ * @param {RequireMachineOptions} [options] - Middleware configuration options.
+ * @returns {RequestHandler} Express middleware handler.
+ */
+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;
+            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;
+            }
+            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,24 @@
+"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;
+};

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

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * @file require-platform-permission.middleware.ts
+ * @description Express middleware generator to enforce platform-scoped permission checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequirePlatformPermission = void 0;
+const permission_checker_1 = require("../authorization/permission-checker");
+const utils_1 = require("../utils");
+/**
+ * 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.
+ */
+const createRequirePlatformPermission = (permissionCache, resolveFn) => {
+    const requirePlatformPermission = (permission) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolvePlatformPermissions(ctx.accountId, async () => {
+                    return resolveFn(ctx.accountId);
+                });
+                if (!permission_checker_1.PermissionChecker.has(perms, permission)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required platform permission: ${permission}`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAnyPlatformPermission = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolvePlatformPermissions(ctx.accountId, async () => {
+                    return resolveFn(ctx.accountId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAny(perms, permissions)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing one of required platform permissions: [${permissions.join(", ")}]`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAllPlatformPermissions = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolvePlatformPermissions(ctx.accountId, async () => {
+                    return resolveFn(ctx.accountId);
+                });
+                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 platform permissions: [${missing.join(", ")}]`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    return {
+        requirePlatformPermission,
+        requireAnyPlatformPermission,
+        requireAllPlatformPermissions,
+    };
+};
+exports.createRequirePlatformPermission = createRequirePlatformPermission;

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

@@ -0,0 +1,14 @@
+/**
+ * @file require-user.middleware.ts
+ * @description Express middleware to assert that the request auth context belongs to a user (not a machine).
+ */
+import { Request, Response, NextFunction } from "express";
+/**
+ * Asserts that the current request has a valid user context, returning 401/403 otherwise.
+ *
+ * @param {Request}      req  - Express request object.
+ * @param {Response}     res  - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
+ * @returns {void}
+ */
+export declare const requireUser: (req: Request, res: Response, next: NextFunction) => void;

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

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * @file require-user.middleware.ts
+ * @description Express middleware to assert that the request auth context belongs to a user (not a machine).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireUser = void 0;
+const utils_1 = require("../utils");
+const types_1 = require("../types");
+/**
+ * Asserts that the current request has a valid user context, returning 401/403 otherwise.
+ *
+ * @param {Request}      req  - Express request object.
+ * @param {Response}     res  - Express response object.
+ * @param {NextFunction} next - Express next middleware function.
+ * @returns {void}
+ */
+const requireUser = (req, res, next) => {
+    const ctx = req.authContext;
+    if (!ctx) {
+        (0, utils_1.failure)(res, req, "Unauthorized: No auth context", "UNAUTHORIZED", 401);
+        return;
+    }
+    if (!(0, types_1.isUserContext)(ctx)) {
+        (0, utils_1.failure)(res, req, "User token required", "FORBIDDEN", 401);
+        return;
+    }
+    next();
+};
+exports.requireUser = requireUser;