@discover-cloud/shared 1.2.9 → 1.4.0

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;

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

@@ -0,0 +1,20 @@
+/**
+ * @file require-workspace-permission.middleware.ts
+ * @description Express middleware factory to enforce workspace-scoped permission checks.
+ */
+import { RequestHandler } from 'express';
+import { Permission } from '../enums';
+import { PermissionCacheService } from '../authorization/permission-cache.service';
+/**
+ * Creates requireWorkspacePermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, workspaceId: string) => Promise<string[]>} resolveFn
+ *   - Function called on a cache miss to fetch the caller's permission strings for the workspace.
+ * @returns {object} Workspace permission middlewares.
+ */
+export declare const createRequireWorkspacePermission: (permissionCache: PermissionCacheService, resolveFn: (accountId: string, workspaceId: string) => Promise<string[]>) => {
+    requireWorkspacePermission: (permission: Permission) => RequestHandler;
+    requireAnyWorkspacePermission: (...permissions: Permission[]) => RequestHandler;
+    requireAllWorkspacePermissions: (...permissions: Permission[]) => RequestHandler;
+};

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

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * @file require-workspace-permission.middleware.ts
+ * @description Express middleware factory to enforce workspace-scoped permission checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireWorkspacePermission = void 0;
+const permission_checker_1 = require("../authorization/permission-checker");
+const utils_1 = require("../utils");
+/**
+ * Creates requireWorkspacePermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, workspaceId: string) => Promise<string[]>} resolveFn
+ *   - Function called on a cache miss to fetch the caller's permission strings for the workspace.
+ * @returns {object} Workspace permission middlewares.
+ */
+const createRequireWorkspacePermission = (permissionCache, resolveFn) => {
+    const requireWorkspacePermission = (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;
+            }
+            // Resolve workspaceId from request locations
+            const workspaceId = req.params['workspaceId'] ??
+                req.validated?.params?.['workspaceId'] ??
+                req.validated?.body?.['workspaceId'];
+            if (!workspaceId || typeof workspaceId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing workspaceId', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                if (!permission_checker_1.PermissionChecker.has(perms, permission)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required workspace permission: ${permission}`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAnyWorkspacePermission = (...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;
+            }
+            const workspaceId = req.params['workspaceId'] ??
+                req.validated?.params?.['workspaceId'] ??
+                req.validated?.body?.['workspaceId'];
+            if (!workspaceId || typeof workspaceId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing workspaceId', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAny(perms, permissions)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing one of required workspace permissions: [${permissions.join(', ')}]`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAllWorkspacePermissions = (...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;
+            }
+            const workspaceId = req.params['workspaceId'] ??
+                req.validated?.params?.['workspaceId'] ??
+                req.validated?.body?.['workspaceId'];
+            if (!workspaceId || typeof workspaceId !== 'string') {
+                (0, utils_1.failure)(res, req, 'Bad Request: Missing workspaceId', 'BAD_REQUEST', 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                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 workspace permissions: [${missing.join(', ')}]`, 'FORBIDDEN', 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    return {
+        requireWorkspacePermission,
+        requireAnyWorkspacePermission,
+        requireAllWorkspacePermissions,
+    };
+};
+exports.createRequireWorkspacePermission = createRequireWorkspacePermission;

package/dist/middleware/validate.middleware.d.ts

@@ -1,35 +1,35 @@
-import { Request, Response, NextFunction } from "express";
-import { ZodType } from "zod";
 /**
- * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Validates and parses request input against a Zod schema.
- * On success, attaches the parsed (coerced + stripped) data to req.validated.
- * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
- *
- * Source options:
- *   "body"    — req.body    (POST/PUT/PATCH payloads)
- *   "params"  — req.params  (URL path parameters)
- *   "query"   — req.query   (URL query string)
- *   "headers" — req.headers (custom header validation, e.g. API keys)
- *
- * Narrowing req.validated in a controller:
- *   req.validated is typed as unknown in express.d.ts — consumers must
- *   narrow it to the schema's inferred type at the call site:
- *
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
- *
- *   This is intentional: the middleware is schema-agnostic and cannot
- *   carry the generic type through Express's untyped req object.
- *
- * Usage:
- *   router.post(
- *     "/orders",
- *     requireAuth,
- *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create,
- *   );
+ * @file validate.middleware.ts
+ * @description Request validation middleware leveraging Zod schema definitions.
+ * Supports validating multiple request sources without overwriting previous results.
+ */
+import { Request, Response, NextFunction } from 'express';
+import { ZodType } from 'zod';
+/**
+ * Supported Express request validation sources.
+ */
+type ValidationSource = 'body' | 'params' | 'query' | 'headers';
+/**
+ * Validator utility class containing Express middleware generation methods.
  */
 export declare class Validator {
-    static validate<T>(schema: ZodType<T>, source?: "body" | "params" | "query" | "headers"): (req: Request, _res: Response, next: NextFunction) => void;
+    /**
+     * Generates middleware to parse and validate request parts.
+     *
+     * Validated data is stored by source:
+     *
+     * req.validated = {
+     *   params: {},
+     *   query: {},
+     *   body: {},
+     *   headers: {}
+     * }
+     *
+     * Multiple validators can safely run on the same request.
+     *
+     * @param {ZodType<T>} schema - Zod validation schema.
+     * @param {ValidationSource} source - Request source.
+     */
+    static validate<T>(schema: ZodType<T>, source?: ValidationSource): (req: Request, _res: Response, next: NextFunction) => void;
 }
+export {};

package/dist/middleware/validate.middleware.js

@@ -1,48 +1,46 @@
 "use strict";
+/**
+ * @file validate.middleware.ts
+ * @description Request validation middleware leveraging Zod schema definitions.
+ * Supports validating multiple request sources without overwriting previous results.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Validator = void 0;
 /**
- * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Validates and parses request input against a Zod schema.
- * On success, attaches the parsed (coerced + stripped) data to req.validated.
- * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
- *
- * Source options:
- *   "body"    — req.body    (POST/PUT/PATCH payloads)
- *   "params"  — req.params  (URL path parameters)
- *   "query"   — req.query   (URL query string)
- *   "headers" — req.headers (custom header validation, e.g. API keys)
- *
- * Narrowing req.validated in a controller:
- *   req.validated is typed as unknown in express.d.ts — consumers must
- *   narrow it to the schema's inferred type at the call site:
- *
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
- *
- *   This is intentional: the middleware is schema-agnostic and cannot
- *   carry the generic type through Express's untyped req object.
- *
- * Usage:
- *   router.post(
- *     "/orders",
- *     requireAuth,
- *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create,
- *   );
+ * Validator utility class containing Express middleware generation methods.
  */
 class Validator {
-    static validate(schema, source = "body") {
+    /**
+     * Generates middleware to parse and validate request parts.
+     *
+     * Validated data is stored by source:
+     *
+     * req.validated = {
+     *   params: {},
+     *   query: {},
+     *   body: {},
+     *   headers: {}
+     * }
+     *
+     * Multiple validators can safely run on the same request.
+     *
+     * @param {ZodType<T>} schema - Zod validation schema.
+     * @param {ValidationSource} source - Request source.
+     */
+    static validate(schema, source = 'body') {
         return (req, _res, next) => {
             const result = schema.safeParse(req[source]);
             if (!result.success) {
-                // Pass the ZodError to GlobalErrorHandler — it flattens and returns 400.
                 next(result.error);
                 return;
             }
-            // Attach the parsed data (coerced + unknown keys stripped by Zod).
-            // req.validated is typed as unknown — narrow to your schema type in the controller.
-            req.validated = result.data;
+            req.validated = {
+                ...(req.validated ?? {}),
+                [source]: {
+                    ...(req.validated?.[source] ?? {}),
+                    ...result.data,
+                },
+            };
             next();
         };
     }

package/dist/types/audit.types.d.ts

@@ -0,0 +1,39 @@
+export declare enum AuditActorType {
+    USER = "USER",
+    SERVICE = "SERVICE",
+    SYSTEM = "SYSTEM",
+    ANONYMOUS = "ANONYMOUS",
+    SUPPORT = "SUPPORT",
+    INTEGRATION = "INTEGRATION",
+    API_KEY = "API_KEY"
+}
+export declare enum AuditResourceType {
+    ACCOUNT = "ACCOUNT",
+    USER = "USER",
+    ORGANIZATION = "ORGANIZATION",
+    WORKSPACE = "WORKSPACE",
+    ROLE = "ROLE",
+    PERMISSION = "PERMISSION",
+    PLATFORM_ROLE = "PLATFORM_ROLE",
+    PLATFORM_PERMISSION = "PLATFORM_PERMISSION",
+    SESSION = "SESSION",
+    SERVICE_CLIENT = "SERVICE_CLIENT",
+    MFA = "MFA",
+    SYSTEM = "SYSTEM",// e.g. for system cron jobs
+    INVITE = "INVITE"
+}
+export declare const AUDIT_SEVERITIES: readonly ["info", "warning", "error", "critical"];
+export type AuditSeverity = (typeof AUDIT_SEVERITIES)[number];
+export interface RecordAuditActionInput {
+    actorId?: string | null;
+    actorType?: AuditActorType;
+    action: string;
+    severity?: AuditSeverity;
+    resourceType: AuditResourceType;
+    resourceId?: string | null;
+    organizationId?: string | null;
+    workspaceId?: string | null;
+    metadata?: Record<string, any>;
+    requestId?: string | null;
+    traceId?: string | null;
+}

package/dist/types/audit.types.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIT_SEVERITIES = exports.AuditResourceType = exports.AuditActorType = void 0;
+var AuditActorType;
+(function (AuditActorType) {
+    AuditActorType["USER"] = "USER";
+    AuditActorType["SERVICE"] = "SERVICE";
+    AuditActorType["SYSTEM"] = "SYSTEM";
+    AuditActorType["ANONYMOUS"] = "ANONYMOUS";
+    AuditActorType["SUPPORT"] = "SUPPORT";
+    AuditActorType["INTEGRATION"] = "INTEGRATION";
+    AuditActorType["API_KEY"] = "API_KEY";
+})(AuditActorType || (exports.AuditActorType = AuditActorType = {}));
+var AuditResourceType;
+(function (AuditResourceType) {
+    AuditResourceType["ACCOUNT"] = "ACCOUNT";
+    AuditResourceType["USER"] = "USER";
+    AuditResourceType["ORGANIZATION"] = "ORGANIZATION";
+    AuditResourceType["WORKSPACE"] = "WORKSPACE";
+    AuditResourceType["ROLE"] = "ROLE";
+    AuditResourceType["PERMISSION"] = "PERMISSION";
+    AuditResourceType["PLATFORM_ROLE"] = "PLATFORM_ROLE";
+    AuditResourceType["PLATFORM_PERMISSION"] = "PLATFORM_PERMISSION";
+    AuditResourceType["SESSION"] = "SESSION";
+    AuditResourceType["SERVICE_CLIENT"] = "SERVICE_CLIENT";
+    AuditResourceType["MFA"] = "MFA";
+    AuditResourceType["SYSTEM"] = "SYSTEM";
+    AuditResourceType["INVITE"] = "INVITE";
+})(AuditResourceType || (exports.AuditResourceType = AuditResourceType = {}));
+exports.AUDIT_SEVERITIES = ["info", "warning", "error", "critical"];