@ozdao/martyrs 0.2.563 → 0.2.565

package/src/modules/core/controllers/classes/abac/abac.js

@@ -9,23 +9,70 @@ import ABACFields from './abac.fields.js';
 import ABACExpressAdapter from './abac.adapter.express.js';
 import ABACWebSocketAdapter from './abac.adapter.ws.js';
 
+/**
+ * @typedef {Object} ABACOptions
+ * @property {boolean} [strictMode=false] - Строгий режим (undefined = deny)
+ * @property {boolean} [defaultDeny=false] - Запрет по умолчанию
+ * @property {string} [serviceKey] - Ключ для сервисных запросов
+ * @property {boolean} [enableAudit=true] - Включить аудит
+ * @property {boolean} [cacheEnabled=true] - Включить кэширование
+ * @property {number} [cacheTTL=300] - TTL кэша в секундах
+ * @property {number} [concurrencyLimit=10] - Лимит параллельных политик
+ * @property {Object} [logger] - Кастомный логгер
+ */
+
+/**
+ * @typedef {Object} ABACContext
+ * @property {string|null} user - ID пользователя
+ * @property {string} action - Действие (read, create, update, delete, etc)
+ * @property {string} resource - Тип ресурса
+ * @property {Object} [currentResource] - Загруженный ресурс
+ * @property {string} [resourceId] - ID ресурса
+ * @property {Object} data - Данные запроса
+ * @property {Object} [data.body] - Body запроса (Express)
+ * @property {Object} [data.query] - Query параметры (Express)
+ * @property {Object} [data.params] - Route параметры (Express)
+ * @property {Object} [req] - Express request
+ * @property {Object} [socket] - WebSocket соединение
+ * @property {Object} [params] - Route параметры
+ * @property {boolean} [skipFieldPolicies=false] - Пропустить проверку полей
+ * @property {Object} [options] - Дополнительные опции
+ */
+
+/**
+ * @typedef {Object} ABACResult
+ * @property {boolean} allow - Разрешен ли доступ
+ * @property {string} reason - Причина решения
+ * @property {Array} [policies] - Примененные политики
+ */
+
+/**
+ * @typedef {Object} FieldsResult
+ * @property {Object} allowed - Разрешенные данные
+ * @property {Array} denied - Запрещенные поля
+ * @property {Array} errors - Ошибки валидации
+ * @property {Object} transformed - Трансформированные данные
+ */
+
 class GlobalABAC {
   constructor(db, options = {}) {
     this.db = db;
+    
+    /** @type {ABACOptions} */
     this.options = {
       strictMode: false,
       defaultDeny: false,
       serviceKey: process.env.SERVICE_KEY,
       enableAudit: true,
       cacheEnabled: true,
-      cacheTTL: 300, // 5 минут
+      cacheTTL: 300,
       concurrencyLimit: 10,
       ...options,
     };
     
     // Инициализация компонентов
     this.cache = new Cache({ ttlSeconds: this.options.cacheTTL });
-    this.logger = options.auditLogger || new Logger(db);
+    this.logger = this.options.logger || new Logger(db);
     
     // Инициализация модулей
     this.core = new ABACCore(this);
@@ -35,53 +82,140 @@ class GlobalABAC {
     this.websocket = new ABACWebSocketAdapter(this);
   }
 
-  // API методы для регистрации политик
+  /**
+   * Регистрация глобальной политики
+   * @param {string} name - Имя политики
+   * @param {Function} policyFn - Функция политики (context) => boolean|{allow, force, reason}
+   * @param {Object} [metadata] - Метаданные политики
+   * @param {string} [metadata.type='dynamic'] - Тип (static|dynamic)
+   * @param {number} [metadata.priority=0] - Приоритет
+   * @returns {GlobalABAC}
+   */
   registerGlobalPolicy(name, policyFn, metadata = {}) {
     return this.policies.registerGlobalPolicy(name, policyFn, metadata);
   }
 
+  /**
+   * Регистрация политики для ресурса
+   * @param {string} resourceName - Имя ресурса
+   * @param {Function} policyFn - Функция политики
+   * @param {Object} [options] - Опции
+   * @param {string} [options.modelName] - Имя модели в БД
+   * @returns {GlobalABAC}
+   */
   registerResourcePolicy(resourceName, policyFn, options = {}) {
     return this.policies.registerResourcePolicy(resourceName, policyFn, options);
   }
 
-  registerFieldsPolicy(resourceName, builderFn) {
-    return this.fields.registerFieldsPolicy(resourceName, builderFn);
+  /**
+   * Регистрация политики полей
+   * @param {string} resourceName - Имя ресурса
+   * @param {Object} config - Конфигурация полей
+   * @returns {GlobalABAC}
+   * 
+   * @example
+   * abac.registerFieldsPolicy('user', {
+   *   'email': { access: 'deny', actions: ['update'] },
+   *   'password': { access: 'deny', actions: '*', rule: 'remove' },
+   *   'profile.*': { 
+   *     access: async (ctx) => ctx.user === ctx.currentResource?.id,
+   *     transform: (value) => sanitize(value)
+   *   }
+   * });
+   */
+  registerFieldsPolicy(resourceName, config) {
+    return this.fields.registerFieldsPolicy(resourceName, config);
   }
 
+  /**
+   * Регистрация расширения контекста
+   * @param {string} moduleName - Имя модуля
+   * @param {Function} extensionFn - Функция расширения (context) => void
+   * @returns {GlobalABAC}
+   */
   registerExtension(moduleName, extensionFn) {
     return this.policies.registerExtension(moduleName, extensionFn);
   }
 
-  // Основные методы проверки
+  /**
+   * Проверка доступа
+   * @param {ABACContext|Object} context - Контекст проверки
+   * @param {Object} [customPolicies] - Дополнительные политики
+   * @returns {Promise<ABACResult>}
+   */
   async checkAccess(context, customPolicies = {}) {
     return this.core.checkAccess(context, customPolicies);
   }
 
-  async checkFields(context, data, action = null, isQuery = false) {
-    return this.fields.checkFields(context, data, action, isQuery);
+  /**
+   * Проверка доступа к полям
+   * @param {ABACContext|Object} context - Контекст
+   * @param {Object} data - Данные для проверки
+   * @param {string} [action] - Действие
+   * @returns {Promise<FieldsResult>}
+   */
+  async checkFields(context, data, action = null) {
+    return this.fields.checkFields(context, data, action);
   }
 
+  /**
+   * Проверка конкретных политик
+   * @param {ABACContext|Object} context - Контекст
+   * @param {string[]} policyNames - Имена политик
+   * @param {Object} [customPolicies] - Дополнительные политики
+   * @returns {Promise<ABACResult>}
+   */
   async checkPolicies(context, policyNames = [], customPolicies = {}) {
     return this.policies.checkPolicies(context, policyNames, customPolicies);
   }
 
-  // Адаптеры
+  /**
+   * Express middleware для проверки доступа
+   * @param {string} resource - Ресурс
+   * @param {string} action - Действие
+   * @param {Object} [options] - Опции
+   * @returns {Function|Function[]} Middleware функция(и)
+   */
   middleware(resource, action, options = {}) {
     return this.express.middleware(resource, action, options);
   }
 
+  /**
+   * Express middleware для проверки политик
+   * @param {string[]} policyNames - Имена политик
+   * @param {Object} [customPolicies] - Дополнительные политики
+   * @param {Object} [options] - Опции
+   * @returns {Function} Middleware функция
+   */
   policyMiddleware(policyNames = [], customPolicies = {}, options = {}) {
     return this.express.policyMiddleware(policyNames, customPolicies, options);
   }
 
+  /**
+   * Express middleware для проверки полей
+   * @param {string} resource - Ресурс
+   * @param {Object} [options] - Опции
+   * @returns {Function} Middleware функция
+   */
   fieldsMiddleware(resource, options = {}) {
     return this.express.fieldsMiddleware(resource, options);
   }
 
+  /**
+   * WebSocket handler
+   * @param {string} moduleName - Имя модуля
+   * @param {Object} [options] - Опции
+   * @returns {Function} Handler функция
+   */
   wsHandler(moduleName, options = {}) {
     return this.websocket.handler(moduleName, options);
   }
   
+  /**
+   * Получение модели ресурса из БД
+   * @param {string} resourceName - Имя ресурса
+   * @returns {Object|null} Mongoose модель или null
+   */
   getResourceModel(resourceName) {
     const resourcePolicy = this.policies.resources.get(resourceName);
     if (!resourcePolicy) return null;
@@ -89,11 +223,61 @@ class GlobalABAC {
     const modelName = resourcePolicy.modelName || resourceName;
     return this.db[modelName] || null;
   }
+
+  /**
+   * Очистка кэша
+   * @param {Object} [options] - Опции очистки
+   * @param {string} [options.user] - Очистить для пользователя
+   * @param {string} [options.resource] - Очистить для ресурса
+   * @param {string} [options.policy] - Очистить для политики
+   */
+  async clearCache(options = {}) {
+    if (options.user) {
+      await this.cache.invalidateTag(`user_${options.user}`);
+    }
+    if (options.resource) {
+      await this.cache.invalidateTag(`resource_${options.resource}`);
+    }
+    if (options.policy) {
+      await this.cache.invalidateTag(`policy_${options.policy}`);
+    }
+    if (!options.user && !options.resource && !options.policy) {
+      await this.cache.clear();
+    }
+  }
+
+  /**
+   * Получение статистики
+   * @returns {Object} Статистика системы
+   */
+  getStats() {
+    return {
+      policies: {
+        global: this.policies.global.size,
+        resources: this.policies.resources.size,
+        extensions: this.policies.extensions.size
+      },
+      fields: {
+        configs: this.fields.configs.size
+      },
+      cache: {
+        size: this.cache.size,
+        hits: this.cache.hits,
+        misses: this.cache.misses
+      }
+    };
+  }
 }
 
 // Экспорт синглтона
 let instance = null;
 
+/**
+ * Получение экземпляра ABAC
+ * @param {Object} db - База данных
+ * @param {ABACOptions} [options] - Опции
+ * @returns {GlobalABAC}
+ */
 export const getInstance = (db, options) => {
   if (!instance) {
     instance = new GlobalABAC(db, options);
@@ -101,4 +285,11 @@ export const getInstance = (db, options) => {
   return instance;
 };
 
-export default { getInstance };
+/**
+ * Сброс экземпляра (для тестов)
+ */
+export const resetInstance = () => {
+  instance = null;
+};
+
+export default { getInstance, resetInstance };

package/src/modules/core/controllers/classes/abac/abac.policies.js

@@ -12,6 +12,9 @@ export default class ABACPolicies {
     };
   }
 
+  /**
+   * Регистрация глобальной политики
+   */
   registerGlobalPolicy(name, policyFn, metadata = {}) {
     if (typeof policyFn !== 'function') {
       throw new Error(`Global policy "${name}" must be a function`);
@@ -20,6 +23,7 @@ export default class ABACPolicies {
     const policy = {
       fn: policyFn,
       type: metadata.type || 'dynamic',
+      priority: metadata.priority || 0,
       ...metadata
     };
     
@@ -28,6 +32,9 @@ export default class ABACPolicies {
     return this.abac;
   }
 
+  /**
+   * Регистрация политики ресурса
+   */
   registerResourcePolicy(resourceName, policyFn, options = {}) {
     if (typeof policyFn !== 'function') {
       throw new Error(`Resource policy for "${resourceName}" must be a function`);
@@ -41,6 +48,9 @@ export default class ABACPolicies {
     return this.abac;
   }
 
+  /**
+   * Регистрация расширения
+   */
   registerExtension(moduleName, extensionFn) {
     if (typeof extensionFn !== 'function') {
       throw new Error(`Extension "${moduleName}" must be a function`);
@@ -51,97 +61,127 @@ export default class ABACPolicies {
     return this.abac;
   }
 
+  /**
+   * Обновление приоритетов с сортировкой
+   */
   updatePriorities() {
-    // Группируем политики по типам
     this.priorities = {
       static: [],
       dynamic: [],
       extensions: []
     };
 
+    // Группируем и сортируем по приоритету
     for (const [name, policy] of this.global) {
       const type = policy.type || 'dynamic';
       this.priorities[type].push([name, policy]);
     }
 
+    // Сортировка по приоритету (выше = раньше)
+    this.priorities.static.sort((a, b) => (b[1].priority || 0) - (a[1].priority || 0));
+    this.priorities.dynamic.sort((a, b) => (b[1].priority || 0) - (a[1].priority || 0));
+
     // Добавляем расширения
     this.priorities.extensions = Array.from(this.extensions.entries());
   }
 
+  /**
+   * Основная логика оценки политик
+   */
   async evaluate(context, customPolicies = {}) {
     const core = this.abac.core;
     
-    // Переменные для отслеживания результатов
-    let hasForceAllow = false;
-    let hasForceDisallow = false;
-    let hasDeny = false;
-    let denyReason = '';
-    let allowReason = '';
+    // Структура для отслеживания результатов
+    const evaluation = {
+      hasForceAllow: false,
+      hasForceDisallow: false,
+      hasDeny: false,
+      denyReason: '',
+      allowReason: '',
+      appliedPolicies: []
+    };
     
     // Функция для обработки результата политики
-    const processResult = (result) => {
+    const processResult = (name, result) => {
+      evaluation.appliedPolicies.push({ name, result });
+      
       if (result.force) {
         if (result.allow) {
-          hasForceAllow = true;
-          allowReason = result.reason;
+          evaluation.hasForceAllow = true;
+          evaluation.allowReason = result.reason;
         } else {
-          hasForceDisallow = true;
-          denyReason = result.reason;
+          evaluation.hasForceDisallow = true;
+          evaluation.denyReason = result.reason;
         }
       } else if (!result.allow) {
-        hasDeny = true;
-        if (!denyReason) denyReason = result.reason;
+        evaluation.hasDeny = true;
+        if (!evaluation.denyReason) {
+          evaluation.denyReason = result.reason;
+        }
       }
     };
     
     // Функция для проверки force флагов
     const checkForceFlags = () => {
-      if (hasForceDisallow) {
+      if (evaluation.hasForceDisallow) {
         return {
           allow: false,
-          reason: denyReason || 'FORCE_DENIED_BY_POLICY',
+          reason: evaluation.denyReason || 'FORCE_DENIED_BY_POLICY',
+          policies: evaluation.appliedPolicies
         };
       }
       
-      if (hasForceAllow) {
+      if (evaluation.hasForceAllow) {
         return {
           allow: true,
-          reason: allowReason || 'FORCE_ALLOWED_BY_POLICY',
+          reason: evaluation.allowReason || 'FORCE_ALLOWED_BY_POLICY',
+          policies: evaluation.appliedPolicies
         };
       }
       
       return null;
     };
     
-    // Выполняем политики по типам
-    for (const type of ['static', 'dynamic']) {
-      const policies = [...this.priorities[type]];
-      
-      // Добавляем кастомные политики к dynamic
-      if (type === 'dynamic') {
-        for (const [name, fn] of Object.entries(customPolicies)) {
-          policies.push([name, { fn, type: 'dynamic' }]);
-        }
+    // 1. Static политики (с early exit)
+    const staticResults = await core.executePoliciesLimited(
+      this.priorities.static, 
+      context,
+      true // останавливаемся на deny
+    );
+
+    for (const { name, result, error } of staticResults) {
+      if (!error) {
+        processResult(name, result);
       }
+    }
+    
+    let forceResult = checkForceFlags();
+    if (forceResult) return forceResult;
 
-      const results = await core.executePoliciesLimited(
-        policies, 
-        context,
-        type === 'static' // Для static останавливаемся на deny
-      );
+    // 2. Dynamic политики + custom
+    const dynamicPolicies = [...this.priorities.dynamic];
+    
+    // Добавляем кастомные политики
+    for (const [name, fn] of Object.entries(customPolicies)) {
+      dynamicPolicies.push([name, { fn, type: 'dynamic' }]);
+    }
+
+    const dynamicResults = await core.executePoliciesLimited(
+      dynamicPolicies, 
+      context,
+      false
+    );
 
-      // Обрабатываем результаты
-      for (const { result, error } of results) {
-        if (error) continue;
-        processResult(result);
+    for (const { name, result, error } of dynamicResults) {
+      if (!error) {
+        processResult(name, result);
       }
-      
-      // Проверяем force флаги после каждого этапа
-      const forceResult = checkForceFlags();
-      if (forceResult) return forceResult;
     }
+    
+    forceResult = checkForceFlags();
+    if (forceResult) return forceResult;
 
-    // Проверка политики ресурса
+    // 3. Resource-specific политика
     const resourcePolicy = this.resources.get(context.resource);
     
     if (resourcePolicy) {
@@ -151,31 +191,36 @@ export default class ABACPolicies {
       );
       
       if (!results[0].error) {
-        processResult(results[0].result);
+        processResult(`RESOURCE_${context.resource}`, results[0].result);
       }
       
-      // Проверяем результат ресурсной политики
-      const forceResult = checkForceFlags();
+      forceResult = checkForceFlags();
       if (forceResult) return forceResult;
     }
     
-    // Проверяем накопленный deny перед расширениями
-    if (hasDeny) {
+    // Проверяем накопленный deny
+    if (evaluation.hasDeny) {
       return {
         allow: false,
-        reason: denyReason || 'DENIED_BY_POLICY',
+        reason: evaluation.denyReason || 'DENIED_BY_POLICY',
+        policies: evaluation.appliedPolicies
       };
     }
 
-    // Выполнение расширений
+    // 4. Extensions (последний шанс разрешить)
     const extensionResults = await core.executePoliciesLimited(
       this.priorities.extensions,
       context
     );
     
-    for (const { result } of extensionResults) {
+    for (const { name, result } of extensionResults) {
+      processResult(name, result);
       if (result.allow) {
-        return { allow: true, reason: result.reason };
+        return { 
+          allow: true, 
+          reason: result.reason,
+          policies: evaluation.appliedPolicies
+        };
       }
     }
 
@@ -184,10 +229,13 @@ export default class ABACPolicies {
     return {
       allow: defaultAllow,
       reason: defaultAllow ? 'DEFAULT_ALLOW' : 'DEFAULT_DENY',
+      policies: evaluation.appliedPolicies
     };
   }
 
-  // Проверка конкретных политик
+  /**
+   * Проверка конкретных политик
+   */
   async checkPolicies(rawContext, policyNames = [], customPolicies = {}) {
     const context = this.abac.core.normalizeContext(rawContext);
     const policies = this.getPoliciesByNames(policyNames, customPolicies);
@@ -198,17 +246,54 @@ export default class ABACPolicies {
       this.abac.options.strictMode
     );
 
-    // Анализируем результаты
-    for (const { result } of results) {
-      if (result.force) return { allow: result.allow, reason: result.reason };
-      if (!result.allow && this.abac.options.strictMode) {
-        return { allow: false, reason: result.reason };
+    // Структурированный анализ результатов
+    const evaluation = {
+      passed: [],
+      failed: [],
+      errors: []
+    };
+
+    for (const { name, result, error } of results) {
+      if (error) {
+        evaluation.errors.push({ name, error: error.message });
+        continue;
+      }
+      
+      if (result.force) {
+        return { 
+          allow: result.allow, 
+          reason: result.reason,
+          evaluation 
+        };
+      }
+      
+      if (result.allow) {
+        evaluation.passed.push(name);
+      } else {
+        evaluation.failed.push({ name, reason: result.reason });
+        
+        if (this.abac.options.strictMode) {
+          return { 
+            allow: false, 
+            reason: result.reason,
+            evaluation
+          };
+        }
       }
     }
 
-    return { allow: true, reason: 'POLICIES_PASSED' };
+    const allPassed = evaluation.failed.length === 0 && evaluation.errors.length === 0;
+    
+    return { 
+      allow: allPassed, 
+      reason: allPassed ? 'POLICIES_PASSED' : `FAILED: ${evaluation.failed[0]?.name}`,
+      evaluation
+    };
   }
 
+  /**
+   * Получение политик по именам
+   */
   getPoliciesByNames(names, customPolicies = {}) {
     const policies = {};
     
@@ -217,9 +302,14 @@ export default class ABACPolicies {
         policies[name] = this.global.get(name);
       } else if (this.extensions.has(name)) {
         policies[name] = { fn: this.extensions.get(name), type: 'extension' };
+      } else if (this.resources.has(name)) {
+        policies[name] = this.resources.get(name);
+      } else {
+        this.abac.logger?.warn('Policy not found', { name });
       }
     }
     
+    // Добавляем кастомные
     Object.assign(policies, customPolicies);
     return policies;
   }

package/src/modules/core/controllers/classes/crud/crud.policies.js

@@ -83,9 +83,9 @@ export default  class CRUDPolicies {
           action,
           req,
           data: {
-            ...req.body,
-            ...req.query,
-            params: req.params,
+            body: req.body || {},
+            query: req.query || {},
+            params: req.params || {}
           },
           params: req.params
         };
@@ -152,8 +152,8 @@ export default  class CRUDPolicies {
       action: 'read',
       req,
       data: {
-        ...req.query,
-        params: req.params,
+        query: req.query || {},
+        params: req.params || {}
       },
       params: req.params
     };

package/src/modules/core/controllers/policies/core.policies.js

@@ -44,9 +44,12 @@ export default (function initializeDefaultPolicies(abacAccessControl) {
     let { user, action, data, currentResource, options } = context;
     const ObjectId = abacAccessControl.db.mongoose.Types.ObjectId;
     // Для create операций с владением пользователя
-    if (action === 'create' && data.owner?.type === 'user') {
+    if (action === 'create' && data.body?.owner?.type === 'user') {
+      const ownerTarget = data.body.owner.target;
+      const creatorTarget = data.body.creator?.target;
+
       // Проверяем, что пользователь создает ресурс от своего имени
-      if (data.owner.target === user && data.creator.target === user) {
+      if (ownerTarget === user && creatorTarget === user) {
         return { allow: true, force: false };
       } else {
         return {