@via-profit/ability 3.6.0 → 3.6.1

package/dist/index.d.ts

@@ -134,6 +134,7 @@ declare class AbilityRule<Resources extends object = object, Environment extends
         resource: AbilityRuleConfig['resource'];
         condition: AbilityConditionType;
     }>): AbilityRule<Resources, Environment>;
+    hash(): string;
     static equals<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
     static notEquals<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
     static contains<Resources extends object = object, Environment extends object = object>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
@@ -199,6 +200,7 @@ declare class AbilityRuleSet<R extends ResourceObject = Record<string, unknown>,
         compareMethod: AbilityCompareType;
         rules: AbilityRule<R, E>[];
     }>): AbilityRuleSet<R, E>;
+    hash(): string;
     static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, Record<string, unknown>>;
     static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, Record<string, unknown>>;
 }
@@ -276,15 +278,15 @@ declare class AbilityPolicy<R extends ResourceObject = Record<string, unknown>,
      * one of the rules returns as «permit»
      */
     compareMethod: AbilityCompareType;
+    /**
+     * Policy ID
+     */
+    id: string;
     /**
      * Policy name
      */
     name: string;
     description?: string | null;
-    /**
-     * Policy ID
-     */
-    id: string;
     /**
      * Running the `enforce` or `resolve` method
      * will select only those from all passed policies that fall under the specified permission key.
@@ -325,6 +327,7 @@ declare class AbilityPolicy<R extends ResourceObject = Record<string, unknown>,
         compareMethod: AbilityCompareType;
         ruleSet: AbilityRuleSet<R, E>[];
     }>): AbilityPolicy<R, E>;
+    hash(): string;
 }
 
 type Primitive = string | number | boolean | null | undefined;
@@ -336,6 +339,7 @@ type EnvironmentObject = Record<string, unknown>;
 type ResourcesMap = Record<string, ResourceObject>;
 declare class AbilityTypeGenerator {
     readonly policies: readonly AbilityPolicy[];
+    private readonly policyEntries;
     constructor(policies: readonly AbilityPolicy[]);
     /**
      * Generates TypeScript type definitions based on the provided policies.
@@ -411,8 +415,8 @@ declare class AbilityResult<R extends ResourceObject = Record<string, unknown>,
      * Useful for debugging, logging, or building UI tools that visualize permission logic.
      */
     explain(): readonly AbilityExplain[];
-    isAllowed(): boolean;
-    isDenied(): boolean;
+    isAllowed: () => boolean;
+    isDenied: () => boolean;
 }
 
 interface AbilityResolverOptions<TTags extends string> {
@@ -420,6 +424,7 @@ interface AbilityResolverOptions<TTags extends string> {
 }
 type ExtractResources<P> = P extends AbilityPolicy<infer R, any, any> ? R : never;
 type ExtractEnvironment<P> = P extends AbilityPolicy<any, infer E, any> ? E : never;
+type ExtractPermission<R> = R extends AbilityResolver<infer P, any, any> ? keyof ExtractResources<P> & string : never;
 type ExtractResourceByPermission<P, Perm extends string> = P extends AbilityPolicy<infer R, any, any> ? (Perm extends keyof R ? R[Perm] : never) : never;
 type ExtractEnvironmentByPermission<P, Perm extends string> = P extends AbilityPolicy<any, infer E, any> ? (Perm extends keyof E ? E[Perm] : never) : never;
 declare class AbilityResolver<P extends AbilityPolicy<any, any, any>, S extends AbilityStrategy<P extends AbilityPolicy<infer R, infer E, any> ? R : never, P extends AbilityPolicy<any, infer E, any> ? E : never>, TTags extends string = P extends AbilityPolicy<any, any, infer T> ? T : never> {
@@ -440,14 +445,16 @@ declare class AbilityResolver<P extends AbilityPolicy<any, any, any>, S extends
     resolve<Permission extends keyof ExtractResources<P> & string>(permission: Permission, resource: ExtractResourceByPermission<P, Permission>, environment?: ExtractEnvironmentByPermission<P, Permission>): AbilityResult<ExtractResourceByPermission<P, Permission>, ExtractEnvironment<P>>;
     enforce<Permission extends keyof ExtractResources<P> & string>(permission: Permission, resource: ExtractResourceByPermission<P, Permission>, environment?: ExtractEnvironmentByPermission<P, Permission>): void | never;
     /**
+     * @deprecated - will be removed
+     *
      * Check if the permission key is contained in another permission key
      * @param permissionA - The first permission to check
      * @param permissionB - The second permission to check
      */
     static isInPermissionContain(permissionA: string, permissionB: string): boolean;
     private toArray;
-    private normalizePermission;
-    private static matchPermissions;
+    static normalizePermission(permission: string): string;
+    static matchPermissions(policySegments: string[], inputSegments: string[]): boolean;
 }
 
 declare class AbilityJSONParser {
@@ -456,13 +463,13 @@ declare class AbilityJSONParser {
      * @param configs - Array of policy configurations
      * @returns Array of AbilityPolicy instances
      */
-    static parse<Resource extends ResourceObject>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resource>[];
-    static parsePolicy<Resource extends ResourceObject = Record<string, unknown>>(config: AbilityPolicyConfig): AbilityPolicy<Resource>;
-    static parseRule<Resources extends object>(config: AbilityRuleConfig): AbilityRule<Resources>;
+    static parse<R extends ResourceObject, E extends EnvironmentObject, T extends string = string>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<R, E, T>[];
+    static parsePolicy<R extends ResourceObject, E extends EnvironmentObject, T extends string = string>(config: AbilityPolicyConfig): AbilityPolicy<R, E, T>;
+    static parseRule<R extends ResourceObject, E extends EnvironmentObject>(config: AbilityRuleConfig): AbilityRule<R, E>;
     /**
      * Parse the config JSON format to Group class instance
      */
-    static parseRuleSet<Resource extends ResourceObject = Record<string, unknown>>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource>;
+    static parseRuleSet<R extends ResourceObject, E extends EnvironmentObject>(config: AbilityRuleSetConfig): AbilityRuleSet<R, E>;
     static ruleToJSON(rule: AbilityRule): AbilityRuleConfig;
     static ruleSetToJSON(ruleSet: AbilityRuleSet): AbilityRuleSetConfig;
     static policyToJSON(policy: AbilityPolicy): AbilityPolicyConfig;
@@ -800,4 +807,4 @@ declare class PriorityStrategy<R extends ResourceObject, E extends EnvironmentOb
 }
 
 export { AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityRule, AbilityRuleSet, AbilityStrategy, AbilityTypeGenerator, AllMustPermitStrategy, AnyPermitStrategy, DenyOverridesStrategy, FirstMatchStrategy, OnlyOneApplicableStrategy, PermitOverridesStrategy, PriorityStrategy, SequentialLastMatchStrategy, TokenTypes, ability, fromLiteral, isConditionEqual, isConditionNotEqual, toLiteral };
-export type { AbilityCompareType, AbilityConditionCode, AbilityConditionLiteral, AbilityConditionType, AbilityExplainConfig, AbilityExplainType, AbilityMatchType, AbilityPolicyConfig, AbilityPolicyConstructorProps, AbilityPolicyEffectType, AbilityResolverOptions, AbilityRuleConfig, AbilityRuleConstructorProps, AbilityRuleSetConfig, AbilityRuleSetConstructorProps, EnvironmentObject, NestedDict, Primitive, ResourceObject, ResourcesMap, TokenType, TokenTypeCode };
+export type { AbilityCompareType, AbilityConditionCode, AbilityConditionLiteral, AbilityConditionType, AbilityExplainConfig, AbilityExplainType, AbilityMatchType, AbilityPolicyConfig, AbilityPolicyConstructorProps, AbilityPolicyEffectType, AbilityResolverOptions, AbilityRuleConfig, AbilityRuleConstructorProps, AbilityRuleSetConfig, AbilityRuleSetConstructorProps, EnvironmentObject, ExtractEnvironment, ExtractEnvironmentByPermission, ExtractPermission, ExtractResourceByPermission, ExtractResources, NestedDict, Primitive, ResourceObject, ResourcesMap, TokenType, TokenTypeCode };

package/dist/index.js

@@ -126,10 +126,198 @@ const AbilityMatch = {
     disabled: brand$2('disabled'),
 };
 
+class AbilityExplain {
+    type;
+    children;
+    name;
+    match;
+    constructor(config, children = []) {
+        this.type = config.type;
+        this.children = children;
+        this.name = config.name;
+        this.match = config.match;
+    }
+    toString(indent = 0) {
+        const pad = ' '.repeat(indent);
+        const mark = this.match === AbilityMatch.match ? '✓' : '✗';
+        let out = '';
+        if (this.type === 'policy') {
+            out += '\n';
+        }
+        out += `${pad}${mark} ${this.type} «${this.name}» is ${this.match}`;
+        this.children.forEach(child => {
+            out += '\n' + child.toString(indent + 1);
+        });
+        return out;
+    }
+}
+class AbilityExplainRule extends AbilityExplain {
+    constructor(rule) {
+        super({
+            type: 'rule',
+            match: rule.state,
+            name: rule.name,
+        });
+    }
+}
+class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet) {
+        const children = ruleSet.rules.map(rule => new AbilityExplainRule(rule));
+        super({
+            type: 'ruleSet',
+            match: ruleSet.state,
+            name: ruleSet.name,
+        }, children);
+    }
+}
+class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy) {
+        const children = policy.ruleSet.map(ruleSet => new AbilityExplainRuleSet(ruleSet));
+        super({
+            type: 'policy',
+            name: policy.priority > -1 ? `@priority ${policy.priority} ${policy.name}` : policy.name,
+            match: policy.matchState,
+        }, children);
+    }
+}
+
+class AbilityResult {
+    effect;
+    strategy;
+    constructor(effect, strategy) {
+        this.effect = effect;
+        this.strategy = strategy;
+    }
+    /**
+     * Returns a list of explanations for each policy involved in the ability evaluation.
+     * Each item describes how a specific policy contributed to the final permission result.
+     *
+     * Useful for debugging, logging, or building UI tools that visualize permission logic.
+     */
+    explain() {
+        return this.strategy.policies.map(policy => {
+            return new AbilityExplainPolicy(policy);
+        });
+    }
+    isAllowed = () => {
+        return this.strategy.isAllowed();
+    };
+    isDenied = () => {
+        return this.strategy.isDenied();
+    };
+}
+
+class AbilityResolver {
+    StrategyClass;
+    policyEntries;
+    constructor(
+    /**
+     * `Important!` The incorrect Resources type was intentionally passed to AbilityPolicy so that TypeScript could suggest the name of the permission and the structure of its resource in the parse method.
+     */
+    policyOrListOfPolicies, strategy, options = {}) {
+        const policies = this.toArray(policyOrListOfPolicies);
+        const filtered = options.tags
+            ? policies.filter(p => p.tags.some(tag => options.tags.includes(tag)))
+            : policies;
+        const sorted = [...filtered].sort((a, b) => b.priority - a.priority);
+        this.policyEntries = sorted.map(policy => ({
+            policy,
+            normalizedPermission: AbilityResolver.normalizePermission(policy.permission),
+            segments: AbilityResolver.normalizePermission(policy.permission).split('.'),
+        }));
+        this.StrategyClass = strategy;
+    }
+    /**
+     * Resolve policy for the resource and permission key
+     *
+     * @param permission - Permission key
+     * @param resource - Resource
+     * @param environment
+     */
+    resolve(permission, resource, environment) {
+        const inputNormalized = AbilityResolver.normalizePermission(String(permission));
+        const inputSegments = inputNormalized.split('.');
+        const filteredPolicies = this.policyEntries
+            .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+            .map(entry => entry.policy);
+        // 2. check the policies
+        for (const policy of filteredPolicies) {
+            if (policy.disabled) {
+                continue;
+            }
+            const policyMatchState = policy.check(resource, environment);
+            if (policyMatchState === AbilityMatch.pending) {
+                throw new AbilityError(`The policy "${policy.name}" is still in a pending state. Make sure to call "check" to evaluate the policy before resolving permissions.`);
+            }
+        }
+        // 3. Use strategy
+        const strategy = new this.StrategyClass(filteredPolicies);
+        const effect = strategy.evaluate();
+        return new AbilityResult(effect, strategy);
+    }
+    enforce(permission, resource, environment) {
+        const result = this.resolve(permission, resource, environment);
+        if (result.isDenied()) {
+            throw new AbilityError(`Permission denied`);
+        }
+    }
+    /**
+     * @deprecated - will be removed
+     *
+     * Check if the permission key is contained in another permission key
+     * @param permissionA - The first permission to check
+     * @param permissionB - The second permission to check
+     */
+    static isInPermissionContain(permissionA, permissionB) {
+        const A = permissionA.split('.');
+        const B = permissionB.split('.');
+        const [longer, shorter] = A.length >= B.length ? [A, B] : [B, A];
+        return shorter.every((chunk, i) => {
+            return chunk === '*' || longer[i] === '*' || chunk === longer[i];
+        });
+    }
+    toArray(value) {
+        return [...(Array.isArray(value) ? value : [value])];
+    }
+    static normalizePermission(permission) {
+        return permission
+            .trim()
+            .replace(/^permission\./, '') // remove prefix
+            .replace(/\.+/g, '.') // collapse multiple dots
+            .toLowerCase(); // optional: make case-insensitive
+    }
+    static matchPermissions(policySegments, inputSegments) {
+        const maxLen = Math.max(policySegments.length, inputSegments.length);
+        for (let i = 0; i < maxLen; i++) {
+            const pSeg = policySegments[i];
+            const iSeg = inputSegments[i];
+            if (pSeg === undefined) {
+                return false;
+            }
+            if (pSeg === '*') {
+                continue; // '*'
+            }
+            if (iSeg === undefined) {
+                return false;
+            }
+            if (pSeg !== iSeg) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+
 class AbilityTypeGenerator {
     policies;
+    policyEntries;
     constructor(policies) {
         this.policies = policies;
+        this.policyEntries = policies.map(policy => ({
+            policy,
+            normalizedPermission: AbilityResolver.normalizePermission(policy.permission),
+            segments: AbilityResolver.normalizePermission(policy.permission).split('.'),
+        }));
     }
     /**
      * Generates TypeScript type definitions based on the provided policies.
@@ -277,21 +465,6 @@ class AbilityTypeGenerator {
      * @returns TypeScript array type as string
      */
     getArrayType(resource) {
-        // if (Array.isArray(resource)) {
-        //   if (resource.length === 0) {
-        //     return 'readonly unknown[]';
-        //   }
-        //   // Determine types of array elements
-        //   const elementTypes = new Set(resource.map(item => this.getPrimitiveType(item)));
-        //   const elementType =
-        //     elementTypes.size === 1
-        //       ? Array.from(elementTypes)[0]
-        //       : `(${Array.from(elementTypes).join(' | ')})`;
-        //   return `readonly ${elementType}[]`;
-        // }
-        // // If resource is not an array but condition is in/not_in,
-        // // it expects an array of such elements
-        // return `readonly ${this.getPrimitiveType(resource)}[]`;
         const elementType = this.getInArrayType(resource);
         return `readonly ${elementType}[]`;
     }
@@ -387,18 +560,43 @@ class AbilityTypeGenerator {
         output += '// Do not edit manually\n';
         output += 'export type Resources = {\n';
         const sortedActions = Object.keys(structure).sort();
-        sortedActions.forEach(action => {
-            const actionObj = structure[action];
+        sortedActions.forEach(permission => {
+            const actionObj = structure[permission];
             const isEmpty = Object.keys(actionObj).length === 0;
+            const inputNormalized = AbilityResolver.normalizePermission(permission);
+            const inputSegments = inputNormalized.split('.');
+            const filteredPolicies = this.policyEntries
+                .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+                .map(entry => entry.policy);
+            // Effects
+            const effects = [...new Set(filteredPolicies.map(p => p.effect))].sort();
+            // Policies list
+            const items = filteredPolicies
+                .sort((a, b) => a.id.localeCompare(b.id))
+                .map(p => {
+                const effect = p.effect.padEnd(6, ' '); // permit / deny / audit
+                const displayName = p.name === p.id ? 'Unnamed policy' : p.name;
+                return `  *   - ${effect} ${p.id}  "${displayName}"`;
+            })
+                .join('\n');
+            //
+            output += `
+ /**
+  * Permission: ${permission}
+  * Effects: ${effects.join(', ')}
+  * Policies:
+${items}
+  */
+`;
             if (isEmpty) {
-                // Пустой объект → undefined
-                output += `  ['${action}']: undefined;\n`;
+                // empty object → undefined
+                output += `  ['${permission}']: undefined;\n`;
             }
             else {
-                // Непустой объект → как раньше
-                output += `  ['${action}']: {\n`;
+                // not empty object
+                output += `  ['${permission}']: {\n`;
                 output += this.formatNestedObject(actionObj, 4);
-                output += '  };\n';
+                output += '  } | null | undefined;\n';
             }
         });
         output += '}\n';
@@ -412,15 +610,37 @@ class AbilityTypeGenerator {
         output += `\n\nexport type PolicyTags = ${tagsUnion};\n`;
         // environments
         output += '\n\nexport type Environment = {\n';
-        Object.entries(environment).forEach(([action, envObj]) => {
+        Object.entries(environment).forEach(([permission, envObj]) => {
             const isEmpty = Object.keys(envObj).length === 0;
+            const inputNormalized = AbilityResolver.normalizePermission(permission);
+            const inputSegments = inputNormalized.split('.');
+            const filteredPolicies = this.policyEntries
+                .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
+                .map(entry => entry.policy);
+            const effects = [...new Set(filteredPolicies.map(p => p.effect))].sort();
+            const items = filteredPolicies
+                .sort((a, b) => a.id.localeCompare(b.id))
+                .map(p => {
+                const effect = p.effect.padEnd(6, ' ');
+                const displayName = p.name === p.id ? 'Unnamed policy' : p.name;
+                return `  *   - ${effect} ${p.id}  "${displayName}"`;
+            })
+                .join('\n');
+            output += `
+ /**
+  * Permission: ${permission}
+  * Effects: ${effects.join(', ')}
+  * Policies:
+${items}
+  */
+`;
             if (isEmpty) {
-                output += `  ['${action}']: undefined;\n`;
+                output += `  ['${permission}']: undefined;\n`;
             }
             else {
-                output += `  ['${action}']: {\n`;
+                output += `  ['${permission}']: {\n`;
                 output += this.formatNestedObject(envObj, 4);
-                output += '  };\n';
+                output += '  } | null | undefined;\n';
             }
         });
         output += '}\n';
@@ -444,69 +664,126 @@ class AbilityTypeGenerator {
                 // Nested object
                 output += `${spaces}readonly ${key}: {\n`;
                 output += this.formatNestedObject(value, indent + 2);
-                output += `${spaces}};\n`;
+                output += `${spaces}} | null | undefined;\n`;
             }
             else {
                 // Primitive type
-                output += `${spaces}readonly ${key}: ${value};\n`;
+                const va = [String(value)];
+                let v = String(value);
+                if (!v.match(/unknown/)) {
+                    if (!v.match(/null/)) {
+                        va.push('null');
+                    }
+                    if (!v.match(/undefined/)) {
+                        va.push('undefined');
+                    }
+                }
+                output += `${spaces}readonly ${key}: ${va.join(' | ')} \n`;
             }
         });
         return output;
     }
 }
 
-class AbilityExplain {
-    type;
-    children;
-    name;
-    match;
-    constructor(config, children = []) {
-        this.type = config.type;
-        this.children = children;
-        this.name = config.name;
-        this.match = config.match;
-    }
-    toString(indent = 0) {
-        const pad = ' '.repeat(indent);
-        const mark = this.match === AbilityMatch.match ? '✓' : '✗';
-        let out = '';
-        if (this.type === 'policy') {
-            out += '\n';
+class AbilityHash {
+    static sha1(message) {
+        const msgBytes = AbilityHash.stringToBytes(message);
+        const msgBitLength = msgBytes.length * 8;
+        const withOne = new Uint8Array(msgBytes.length + 1);
+        withOne.set(msgBytes, 0);
+        withOne[msgBytes.length] = 0x80;
+        let zeroBytes = (56 - (withOne.length % 64) + 64) % 64;
+        const padded = new Uint8Array(withOne.length + zeroBytes + 8);
+        padded.set(withOne, 0);
+        const bitLenHigh = Math.floor(msgBitLength / 0x100000000);
+        const bitLenLow = msgBitLength >>> 0;
+        padded[padded.length - 8] = (bitLenHigh >>> 24) & 0xff;
+        padded[padded.length - 7] = (bitLenHigh >>> 16) & 0xff;
+        padded[padded.length - 6] = (bitLenHigh >>> 8) & 0xff;
+        padded[padded.length - 5] = bitLenHigh & 0xff;
+        padded[padded.length - 4] = (bitLenLow >>> 24) & 0xff;
+        padded[padded.length - 3] = (bitLenLow >>> 16) & 0xff;
+        padded[padded.length - 2] = (bitLenLow >>> 8) & 0xff;
+        padded[padded.length - 1] = bitLenLow & 0xff;
+        let h0 = 0x67452301;
+        let h1 = 0xefcdab89;
+        let h2 = 0x98badcfe;
+        let h3 = 0x10325476;
+        let h4 = 0xc3d2e1f0;
+        const w = new Array(80);
+        for (let i = 0; i < padded.length; i += 64) {
+            for (let j = 0; j < 16; j++) {
+                const idx = i + j * 4;
+                w[j] =
+                    (padded[idx] << 24) | (padded[idx + 1] << 16) | (padded[idx + 2] << 8) | padded[idx + 3];
+            }
+            for (let j = 16; j < 80; j++) {
+                w[j] = AbilityHash.leftRotate(w[j - 3] ^ w[j - 8] ^ w[j - 14] ^ w[j - 16], 1);
+            }
+            let a = h0;
+            let b = h1;
+            let c = h2;
+            let d = h3;
+            let e = h4;
+            for (let j = 0; j < 80; j++) {
+                let f;
+                let k;
+                if (j < 20) {
+                    f = (b & c) | (~b & d);
+                    k = 0x5a827999;
+                }
+                else {
+                    if (j < 40) {
+                        f = b ^ c ^ d;
+                        k = 0x6ed9eba1;
+                    }
+                    else {
+                        if (j < 60) {
+                            f = (b & c) | (b & d) | (c & d);
+                            k = 0x8f1bbcdc;
+                        }
+                        else {
+                            f = b ^ c ^ d;
+                            k = 0xca62c1d6;
+                        }
+                    }
+                }
+                const temp = (AbilityHash.leftRotate(a, 5) + f + e + k + (w[j] | 0)) | 0;
+                e = d;
+                d = c;
+                c = AbilityHash.leftRotate(b, 30);
+                b = a;
+                a = temp;
+            }
+            h0 = (h0 + a) | 0;
+            h1 = (h1 + b) | 0;
+            h2 = (h2 + c) | 0;
+            h3 = (h3 + d) | 0;
+            h4 = (h4 + e) | 0;
+        }
+        return [
+            AbilityHash.toHex32(h0),
+            AbilityHash.toHex32(h1),
+            AbilityHash.toHex32(h2),
+            AbilityHash.toHex32(h3),
+            AbilityHash.toHex32(h4),
+        ].join('');
+    }
+    static leftRotate(value, bits) {
+        return ((value << bits) | (value >>> (32 - bits))) >>> 0;
+    }
+    static toHex32(num) {
+        return (num >>> 0).toString(16).padStart(8, '0');
+    }
+    static stringToBytes(str) {
+        if (typeof TextEncoder !== 'undefined') {
+            const encoder = new TextEncoder();
+            return encoder.encode(str);
+        }
+        else {
+            const buf = Buffer.from(str, 'utf8');
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
         }
-        out += `${pad}${mark} ${this.type} «${this.name}» is ${this.match}`;
-        this.children.forEach(child => {
-            out += '\n' + child.toString(indent + 1);
-        });
-        return out;
-    }
-}
-class AbilityExplainRule extends AbilityExplain {
-    constructor(rule) {
-        super({
-            type: 'rule',
-            match: rule.state,
-            name: rule.name,
-        });
-    }
-}
-class AbilityExplainRuleSet extends AbilityExplain {
-    constructor(ruleSet) {
-        const children = ruleSet.rules.map(rule => new AbilityExplainRule(rule));
-        super({
-            type: 'ruleSet',
-            match: ruleSet.state,
-            name: ruleSet.name,
-        }, children);
-    }
-}
-class AbilityExplainPolicy extends AbilityExplain {
-    constructor(policy) {
-        const children = policy.ruleSet.map(ruleSet => new AbilityExplainRuleSet(ruleSet));
-        super({
-            type: 'policy',
-            name: policy.priority > -1 ? `@priority ${policy.priority} ${policy.name}` : policy.name,
-            match: policy.matchState,
-        }, children);
     }
 }
 
@@ -527,15 +804,15 @@ class AbilityPolicy {
      * one of the rules returns as «permit»
      */
     compareMethod = AbilityCompare.and;
+    /**
+     * Policy ID
+     */
+    id;
     /**
      * Policy name
      */
     name;
     description;
-    /**
-     * Policy ID
-     */
-    id;
     /**
      * Running the `enforce` or `resolve` method
      * will select only those from all passed policies that fall under the specified permission key.
@@ -546,8 +823,6 @@ class AbilityPolicy {
     tags;
     constructor(params) {
         const { name, description, id, permission, effect, compareMethod = AbilityCompare.and, priority, disabled, tags, } = params;
-        this.id = id || `policy:${effect}:${permission}`;
-        this.name = name || this.id;
         this.permission = permission;
         this.description = description;
         this.effect = effect;
@@ -555,6 +830,8 @@ class AbilityPolicy {
         this.priority = typeof priority === 'number' ? priority : -1;
         this.disabled = typeof disabled === 'boolean' ? disabled : false;
         this.tags = (tags || []);
+        this.id = id || `p_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
     /**
      * Add rule set to the policy
@@ -668,6 +945,24 @@ class AbilityPolicy {
         }
         return policy;
     }
+    hash() {
+        const parts = [
+            `permission:${this.permission}`,
+            `effect:${this.effect}`,
+            `compareMethod:${this.compareMethod}`,
+            `priority:${this.priority}`,
+            `disabled:${this.disabled}`,
+        ];
+        if (this.tags && this.tags.length > 0) {
+            parts.push(`tags:${[...this.tags].sort().join(',')}`);
+        }
+        if (this.ruleSet && this.ruleSet.length > 0) {
+            const ruleHashes = this.ruleSet.map(r => r.hash());
+            parts.push(`rules:${ruleHashes.sort().join('|')}`);
+        }
+        const str = parts.join(';');
+        return AbilityHash.sha1(str);
+    }
 }
 
 function brand$1(code) {
@@ -678,127 +973,6 @@ const AbilityPolicyEffect = {
     permit: brand$1('permit'),
 };
 
-class AbilityResult {
-    effect;
-    strategy;
-    constructor(effect, strategy) {
-        this.effect = effect;
-        this.strategy = strategy;
-    }
-    /**
-     * Returns a list of explanations for each policy involved in the ability evaluation.
-     * Each item describes how a specific policy contributed to the final permission result.
-     *
-     * Useful for debugging, logging, or building UI tools that visualize permission logic.
-     */
-    explain() {
-        return this.strategy.policies.map(policy => {
-            return new AbilityExplainPolicy(policy);
-        });
-    }
-    isAllowed() {
-        return this.strategy.isAllowed();
-    }
-    isDenied() {
-        return this.strategy.isDenied();
-    }
-}
-
-class AbilityResolver {
-    StrategyClass;
-    policyEntries;
-    constructor(
-    /**
-     * `Important!` The incorrect Resources type was intentionally passed to AbilityPolicy so that TypeScript could suggest the name of the permission and the structure of its resource in the parse method.
-     */
-    policyOrListOfPolicies, strategy, options = {}) {
-        const policies = this.toArray(policyOrListOfPolicies);
-        const filtered = options.tags
-            ? policies.filter(p => p.tags.some(tag => options.tags.includes(tag)))
-            : policies;
-        const sorted = [...filtered].sort((a, b) => b.priority - a.priority);
-        this.policyEntries = sorted.map(policy => ({
-            policy,
-            normalizedPermission: this.normalizePermission(policy.permission),
-            segments: this.normalizePermission(policy.permission).split('.'),
-        }));
-        this.StrategyClass = strategy;
-    }
-    /**
-     * Resolve policy for the resource and permission key
-     *
-     * @param permission - Permission key
-     * @param resource - Resource
-     * @param environment
-     */
-    resolve(permission, resource, environment) {
-        const inputNormalized = this.normalizePermission(String(permission));
-        const inputSegments = inputNormalized.split('.');
-        const filteredPolicies = this.policyEntries
-            .filter(entry => AbilityResolver.matchPermissions(entry.segments, inputSegments))
-            .map(entry => entry.policy);
-        // 2. check the policies
-        for (const policy of filteredPolicies) {
-            if (policy.disabled) {
-                continue;
-            }
-            const policyMatchState = policy.check(resource, environment);
-            if (policyMatchState === AbilityMatch.pending) {
-                throw new AbilityError(`The policy "${policy.name}" is still in a pending state. Make sure to call "check" to evaluate the policy before resolving permissions.`);
-            }
-        }
-        // 3. Use strategy
-        const strategy = new this.StrategyClass(filteredPolicies);
-        const effect = strategy.evaluate();
-        return new AbilityResult(effect, strategy);
-    }
-    enforce(permission, resource, environment) {
-        const result = this.resolve(permission, resource, environment);
-        if (result.isDenied()) {
-            throw new AbilityError(`Permission denied`);
-        }
-    }
-    /**
-     * Check if the permission key is contained in another permission key
-     * @param permissionA - The first permission to check
-     * @param permissionB - The second permission to check
-     */
-    static isInPermissionContain(permissionA, permissionB) {
-        const A = permissionA.split('.');
-        const B = permissionB.split('.');
-        const [longer, shorter] = A.length >= B.length ? [A, B] : [B, A];
-        return shorter.every((chunk, i) => {
-            return chunk === '*' || longer[i] === '*' || chunk === longer[i];
-        });
-    }
-    toArray(value) {
-        return [...(Array.isArray(value) ? value : [value])];
-    }
-    normalizePermission(permission) {
-        return permission
-            .trim()
-            .replace(/^permission\./, '') // remove prefix
-            .replace(/\.+/g, '.') // collapse multiple dots
-            .toLowerCase(); // optional: make case-insensitive
-    }
-    static matchPermissions(policySegments, inputSegments) {
-        const maxLen = Math.max(policySegments.length, inputSegments.length);
-        for (let i = 0; i < maxLen; i++) {
-            const pSeg = policySegments[i];
-            const iSeg = inputSegments[i];
-            if (pSeg === undefined)
-                return false; // policy короче – не матчит
-            if (pSeg === '*')
-                continue; // '*' матчит любой сегмент
-            if (iSeg === undefined)
-                return false; // входной permission короче
-            if (pSeg !== iSeg)
-                return false;
-        }
-        return true;
-    }
-}
-
 /**
  * Represents a rule that defines a condition to be checked against a subject and resource.
  */
@@ -829,14 +1003,14 @@ class AbilityRule {
      */
     constructor(params) {
         const { id, name, subject, resource, condition, disabled, description } = params;
-        this.name = name || `rule:${JSON.stringify(subject)}:${condition}:${JSON.stringify(resource)}`;
-        this.id = id || this.name;
         this.description = description;
         this.disabled = typeof disabled === 'boolean' ? disabled : false;
         this.subject = subject;
         this.resource = resource;
         this.condition = condition;
         this.state = this.disabled ? AbilityMatch.disabled : this.state;
+        this.id = id || `r_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
     static isPrimitive(v) {
         return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null;
@@ -1063,6 +1237,14 @@ class AbilityRule {
             condition: props.condition ?? this.condition,
         });
     }
+    hash() {
+        const parts = [];
+        parts.push(`subject:${this.subject}`);
+        parts.push(`resource:${JSON.stringify(this.resource)}`);
+        parts.push(`condition:${this.condition}`);
+        parts.push(`disabled:${this.disabled}`);
+        return AbilityHash.sha1(parts.join(';'));
+    }
     static equals(subject, resource) {
         return new AbilityRule({
             condition: AbilityCondition.equals,
@@ -1168,13 +1350,13 @@ class AbilityRuleSet {
     disabled;
     constructor(params) {
         const { name, id, compareMethod, isExcept, disabled, description } = params;
-        this.name = name || `ruleset:${compareMethod}`;
-        this.id = id || this.name;
         this.description = description;
         this.compareMethod = compareMethod;
         this.isExcept = isExcept;
         this.disabled = typeof disabled === 'boolean' ? disabled : false;
         this.state = this.disabled ? AbilityMatch.disabled : this.state;
+        this.id = id || `g_${this.hash().slice(0, 10)}`;
+        this.name = name || this.id;
     }
     addRule(rule) {
         this.rules.push(rule);
@@ -1236,6 +1418,16 @@ class AbilityRuleSet {
         }
         return next;
     }
+    hash() {
+        const ruleHashes = this.rules.map(r => r.hash()).sort();
+        const parts = [
+            `compareMethod:${this.compareMethod}`,
+            `isExcept:${this.isExcept}`,
+            `disabled:${this.disabled}`,
+            `rules:${ruleHashes.join('|')}`,
+        ];
+        return AbilityHash.sha1(parts.join(';'));
+    }
     static and(rules) {
         return new AbilityRuleSet({
             compareMethod: AbilityCompare.and,
@@ -1508,11 +1700,49 @@ class AbilityDSLLexer {
     readAnnotation() {
         const startLine = this.line;
         const startColumn = this.column;
-        let value = '';
+        let raw = '';
+        // читаем всю строку после @
         while (!this.isAtEnd() && !this.isNewline()) {
-            value += this.advance();
+            raw += this.advance();
+        }
+        raw = raw.trim();
+        // parse literals
+        let result = '';
+        let i = 0;
+        let inString = false;
+        let quote = null;
+        let escaped = false;
+        while (i < raw.length) {
+            const ch = raw[i];
+            if (inString) {
+                if (escaped) {
+                    result += ch;
+                    escaped = false;
+                }
+                else if (ch === '\\') {
+                    escaped = true;
+                }
+                else if (ch === quote) {
+                    inString = false;
+                    quote = null;
+                }
+                else {
+                    result += ch;
+                }
+                i++;
+                continue;
+            }
+            // start of string
+            if (ch === '"' || ch === "'") {
+                inString = true;
+                quote = ch;
+                i++;
+                continue;
+            }
+            result += ch;
+            i++;
         }
-        return new AbilityDSLToken(TokenTypes.ANNOTATION, value.trim(), startLine, startColumn);
+        return new AbilityDSLToken(TokenTypes.ANNOTATION, result.trim(), startLine, startColumn);
     }
     readString() {
         const startLine = this.line;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@via-profit/ability",
   "support": "https://via-profit.ru",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "description": "Via-Profit Ability service",
   "keywords": [
     "ability",