@via-profit/ability 2.1.0 → 3.1.0

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+I take the security of `@via-profit/ability` seriously. If you discover a security vulnerability, please report it responsibly.
+
+### How to Report a Vulnerability
+
+**Please DO NOT create a public GitHub issue for security vulnerabilities.**
+
+Instead, send the details directly to me:
+
+- **Email**: [delhsmail@gmail.com](mailto:delhsmail@gmail.com)
+- **Author**: Vasily Novosad
+- **Timezone**: UTC+5 (for coordinating response time)
+
+### What to Include
+
+To help me address the issue quickly, please include:
+
+- Description of the vulnerability
+- Steps to reproduce (if applicable)
+- Potential impact
+- Suggestions for fixing (if any)
+
+### Process
+
+1. I will acknowledge your report within 48 hours
+2. I will assess the vulnerability
+3. Work on a fix will begin depending on severity
+4. After the fix is released, I will notify you and acknowledge your contribution (if you agree)
+
+Thank you for helping keep this project secure!

package/dist/cache/AbilityCacheAdapter.d.ts

@@ -0,0 +1,8 @@
+export interface AbilityCacheAdapter {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    serialize<T = unknown>(input: T): string;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+}

package/dist/cache/AbilityInMemoryCache.d.ts

@@ -0,0 +1,12 @@
+import { AbilityCacheAdapter } from '../cache/AbilityCacheAdapter';
+export declare class AbilityInMemoryCache implements AbilityCacheAdapter {
+    private store;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    serialize(input: unknown): string;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+    private fastHash;
+    private stableStringify;
+}

package/dist/core/AbilityCondition.d.ts

@@ -0,0 +1,21 @@
+import AbilityCode from './AbilityCode';
+export type AbilityConditionCodeType = '=' | '<>' | '>' | '<' | '>=' | '<=' | 'in' | 'not in' | 'contains' | 'not contains' | 'length greater than' | 'length less than' | 'length equals';
+export type AbilityConditionLiteralType = 'equals' | 'not_equals' | 'contains' | 'no_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than' | 'less_or_equal' | 'greater_or_equal' | 'length_greater_than' | 'length_less_than' | 'length_equals';
+export declare class AbilityCondition extends AbilityCode<AbilityConditionCodeType> {
+    static equals: AbilityCondition;
+    static not_equals: AbilityCondition;
+    static greater_than: AbilityCondition;
+    static less_than: AbilityCondition;
+    static less_or_equal: AbilityCondition;
+    static greater_or_equal: AbilityCondition;
+    static in: AbilityCondition;
+    static not_in: AbilityCondition;
+    static contains: AbilityCondition;
+    static not_contains: AbilityCondition;
+    static length_greater_than: AbilityCondition;
+    static length_less_than: AbilityCondition;
+    static length_equals: AbilityCondition;
+    static fromLiteral(literal: AbilityConditionLiteralType): AbilityCondition;
+    get literal(): AbilityConditionLiteralType;
+}
+export default AbilityCondition;

package/dist/core/AbilityExplain.d.ts

@@ -0,0 +1,27 @@
+import AbilityRule from './AbilityRule';
+import AbilityRuleSet from '../core/AbilityRuleSet';
+import AbilityPolicy from '../core/AbilityPolicy';
+import AbilityMatch from '../core/AbilityMatch';
+export type AbilityExplainConfig = {
+    readonly type: AbilityExplainType;
+    readonly name: string;
+    readonly match: AbilityMatch;
+};
+export declare class AbilityExplain {
+    readonly type: AbilityExplainType;
+    readonly children: AbilityExplain[];
+    readonly name: string;
+    readonly match: AbilityMatch;
+    constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
+    toString(indent?: number): string;
+}
+export declare class AbilityExplainRule extends AbilityExplain {
+    constructor(rule: AbilityRule);
+}
+export declare class AbilityExplainRuleSet extends AbilityExplain {
+    constructor(ruleSet: AbilityRuleSet);
+}
+export declare class AbilityExplainPolicy extends AbilityExplain {
+    constructor(policy: AbilityPolicy);
+}
+export type AbilityExplainType = 'policy' | 'rule' | 'ruleSet';

package/dist/core/AbilityParser.d.ts

@@ -0,0 +1,61 @@
+import AbilityPolicy from './AbilityPolicy';
+export type Primitive = string | number | boolean | null | undefined;
+export type NestedDict<T = Primitive> = {
+    [key: string]: NestedDict<T> | T;
+};
+export type ResourceObject = Record<string, unknown>;
+export type ResourcesMap = Record<string, ResourceObject>;
+export declare class AbilityParser {
+    /**
+     * Sets a value in a nested object structure based on a dot/bracket notation path.
+     * @param object - The target object to modify.
+     * @param path - The path to the property in dot/bracket notation.
+     * @param value - The value to set at the specified path.
+     */
+    static setValueDotValue<T extends Primitive>(object: NestedDict<T>, path: string, value: T): void;
+    /**
+     * Generates TypeScript type definitions based on the provided policies.
+     * @param policies - An array of AbilityPolicy instances.
+     * @returns A generated type definitions.
+     */
+    static generateTypeDefs(policies: readonly AbilityPolicy[]): string;
+    /**
+     * Determines TypeScript type based on the rule
+     * @param rule - The rule to analyze
+     * @returns TypeScript type as string
+     */
+    private static determineTypeFromRule;
+    /**
+     * Gets TypeScript type for array values
+     * @param resource - The resource value to analyze
+     * @returns TypeScript array type as string
+     */
+    private static getArrayType;
+    /**
+     * Gets primitive TypeScript type for a value
+     * @param value - The value to analyze
+     * @returns TypeScript primitive type as string
+     */
+    private static getPrimitiveType;
+    /**
+     * Builds nested structure from flat paths
+     * Example: 'user.profile.name' -> { user: { profile: { name: 'string' } } }
+     * @param flatStructure - Flat structure with dot notation paths
+     * @returns Nested object structure
+     */
+    private static buildNestedStructure;
+    /**
+     * Formats type structure into a string
+     * @param structure - Nested type structure
+     * @returns Formatted TypeScript type definition string
+     */
+    private static formatTypeDefinitions;
+    /**
+     * Recursively formats nested object
+     * @param obj - Object to format
+     * @param indent - Current indentation level
+     * @returns Formatted string
+     */
+    private static formatNestedObject;
+}
+export default AbilityParser;

package/dist/core/AbilityPolicy.d.ts

@@ -0,0 +1,84 @@
+import AbilityRuleSet, { AbilityRuleSetConfig } from './AbilityRuleSet';
+import AbilityMatch from './AbilityMatch';
+import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
+import AbilityPolicyEffect, { AbilityPolicyEffectCodeType } from './AbilityPolicyEffect';
+import { AbilityExplain } from './AbilityExplain';
+import { ResourceObject } from './AbilityParser';
+export type AbilityPolicyConfig = {
+    readonly permission: string;
+    readonly effect: AbilityPolicyEffectCodeType;
+    readonly compareMethod: AbilityCompareCodeType;
+    readonly ruleSet: readonly AbilityRuleSetConfig[];
+    readonly id: string;
+    readonly name: string;
+};
+export type AbilityPolicyConstructorProps = {
+    id: string;
+    name: string;
+    permission: string;
+    effect: AbilityPolicyEffect;
+    compareMethod?: AbilityCompare;
+};
+export declare class AbilityPolicy<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown> {
+    matchState: AbilityMatch;
+    /**
+     * List of rules
+     */
+    ruleSet: AbilityRuleSet<Resource, Environment>[];
+    /**
+     * Policy effect
+     */
+    effect: AbilityPolicyEffect;
+    /**
+     * Rules compare method.\
+     * For the «and» method the rule will be permitted if all\
+     * rules will be returns «permit» status and for the «or» - if\
+     * one of the rules returns as «permit»
+     */
+    compareMethod: AbilityCompare;
+    /**
+     * Policy name
+     */
+    name: string;
+    /**
+     * 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.
+     */
+    permission: string;
+    constructor(params: AbilityPolicyConstructorProps);
+    /**
+     * Add rule set to the policy
+     * @param ruleSet - The rule set to add
+     */
+    addRuleSet(ruleSet: AbilityRuleSet<Resource, Environment>): this;
+    /**
+     * Add rule set to the policy
+     * @param ruleSets - The array of rule set to add
+     */
+    addRuleSets(ruleSets: readonly AbilityRuleSet<Resource, Environment>[]): this;
+    /**
+     * Check if the policy is matched
+     * @param resource - The resource to check
+     * @param environment - The user environment object
+     */
+    check(resource: Resource, environment?: Environment): Promise<AbilityMatch>;
+    explain(): AbilityExplain;
+    /**
+     * Parses an array of policy configurations into an array of AbilityPolicy instances.
+     * @param configs - Array of policy configurations
+     * @returns Array of AbilityPolicy instances
+     */
+    static fromJSONAll<Resource extends ResourceObject, Environment = unknown>(configs: readonly AbilityPolicyConfig[]): AbilityPolicy<Resource, Environment>[];
+    /**
+     * Parse the config JSON format to Policy class instance
+     */
+    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityPolicyConfig): AbilityPolicy<Resource, Environment>;
+    static fromDSL<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(dsl: string): AbilityPolicy<Resource, Environment>;
+    toJSON(): AbilityPolicyConfig;
+    toString(): string;
+}
+export default AbilityPolicy;

package/dist/core/AbilityResolver.d.ts

@@ -0,0 +1,35 @@
+import AbilityPolicy from './AbilityPolicy';
+import { AbilityResult } from './AbilityResult';
+import { ResourcesMap } from './AbilityParser';
+import { AbilityCacheAdapter } from '../cache/AbilityCacheAdapter';
+export type AbilityResolverOptions = {
+    readonly cache?: AbilityCacheAdapter | null;
+};
+export declare class AbilityResolver<Resources extends ResourcesMap, Environment = unknown> {
+    private policies;
+    private readonly cache?;
+    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: readonly AbilityPolicy<Resources>[] | AbilityPolicy<Resources>, options?: AbilityResolverOptions);
+    /**
+     * Resolve policy for the resource and permission key
+     *
+     * @param permission - Permission key
+     * @param resource - Resource
+     * @param environment
+     */
+    resolve<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): Promise<AbilityResult<Resources[Permission]>>;
+    enforce<Permission extends keyof Resources>(permission: Permission, resource: Resources[Permission], environment?: Environment): Promise<void | never>;
+    /**
+     * 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 makeCacheKey;
+    invalidatePolicy(policyId: string): Promise<void>;
+    invalidateCache(): Promise<void>;
+}
+export default AbilityResolver;

package/dist/core/AbilityResult.d.ts

@@ -0,0 +1,27 @@
+import { AbilityExplain } from './AbilityExplain';
+import { ResourceObject } from './AbilityParser';
+import AbilityPolicy from './AbilityPolicy';
+import AbilityPolicyEffect from './AbilityPolicyEffect';
+export declare class AbilityResult<Resource extends ResourceObject = Record<string, unknown>> {
+    /**
+     * Already checked policies (after call the policy.check())
+     */
+    readonly policies: readonly AbilityPolicy<Resource>[];
+    constructor(policies: readonly AbilityPolicy<Resource>[]);
+    /**
+     * 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(): readonly AbilityExplain[];
+    getLastMatchedPolicy(): AbilityPolicy<Resource> | null;
+    isAllowed(): boolean;
+    isDenied(): boolean;
+    /**
+     * Get the last effect of the policy
+     *
+     * @returns {AbilityPolicyEffect | null}
+     */
+    getLastEffectOfMatchedPolicy(): AbilityPolicyEffect | null;
+}

package/dist/core/AbilityRule.d.ts

@@ -0,0 +1,77 @@
+import AbilityMatch from './AbilityMatch';
+import AbilityCondition, { AbilityConditionCodeType } from './AbilityCondition';
+export type AbilityRuleConfig = {
+    readonly id?: string | null;
+    readonly name?: string | null;
+    /**
+     * Subject key path like a 'user.name'
+     */
+    readonly subject: string;
+    /**
+     * Resource key path like a 'user.name' or value
+     */
+    readonly resource: string | number | boolean | null | (string | number | boolean | null)[];
+    readonly condition: AbilityConditionCodeType;
+};
+export type AbilityRuleConstructorProps = Omit<AbilityRuleConfig, 'condition'> & {
+    readonly condition: AbilityCondition;
+};
+/**
+ * Represents a rule that defines a condition to be checked against a subject and resource.
+ */
+export declare class AbilityRule<Resources extends object = object, Environment = unknown> {
+    /**
+     * Subject key path like a 'user.name'
+     */
+    subject: string;
+    /**
+     * Resource key path like a 'user.name' or value
+     */
+    resource: AbilityRuleConfig['resource'];
+    condition: AbilityCondition;
+    name: string;
+    id: string;
+    state: AbilityMatch;
+    /**
+     * Creates an instance of AbilityRule.
+     * @param {string} params.id - The unique identifier of the rule.
+     * @param {string} params.name - The name of the rule.
+     * @param {AbilityCondition} params.condition - The condition to evaluate.
+     * @param {string} params.subject - The subject of the rule.
+     * @param {string} params.resource - The resource to compare against.
+     * @param params
+     */
+    constructor(params: AbilityRuleConstructorProps);
+    /**
+     * Check if the rule is matched
+     * @param resource - The resource to check
+     * @param environment
+     */
+    check(resource: Resources | null, environment?: Environment): Promise<AbilityMatch>;
+    /**
+     * Extract values from the resourceData
+     * @param resourceData - The resourceData to extract values from
+     * @param environment - Environment data
+     */
+    extractValues(resourceData: Resources | null, environment?: Environment | null): [AbilityRuleConfig['resource'] | undefined, AbilityRuleConfig['resource'] | undefined];
+    /**
+     * Get the value of the object by dot notation
+     * @param resource - The object to get the value from
+     * @param desc - The dot notation string
+     */
+    getDotNotationValue<T = unknown>(resource: unknown, desc: string): T | undefined;
+    toString(): string;
+    static fromJSON<Resources extends object, Environment = unknown>(config: AbilityRuleConfig): AbilityRule<Resources, Environment>;
+    static equals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEquals<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static contains<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notContains<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notIn<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static in<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static notEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessThan<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static lessOrEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreThan<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+    static moreOrEqual<Resources extends object = object, Environment = unknown>(subject: string, resource: AbilityRuleConfig['resource']): AbilityRule<Resources, Environment>;
+}
+export default AbilityRule;

package/dist/{AbilityRuleSet.d.ts → core/AbilityRuleSet.d.ts}

@@ -1,23 +1,24 @@
 import AbilityRule, { AbilityRuleConfig } from './AbilityRule';
 import AbilityCompare, { AbilityCompareCodeType } from './AbilityCompare';
 import AbilityMatch from './AbilityMatch';
+import { ResourceObject } from './AbilityParser';
 export type AbilityRuleSetConfig = {
-    readonly id: string;
-    readonly name: string;
+    readonly id?: string | null;
+    readonly name?: string | null;
     readonly compareMethod: AbilityCompareCodeType;
     readonly rules: readonly AbilityRuleConfig[];
 };
 export type AbilityRuleSetConstructorProps = {
-    readonly id: string;
-    readonly name: string;
+    readonly id?: string | null;
+    readonly name?: string | null;
     readonly compareMethod: AbilityCompare;
 };
-export declare class AbilityRuleSet<Resources extends object = object> {
+export declare class AbilityRuleSet<Resources extends ResourceObject = Record<string, unknown>, Environment = unknown> {
     state: AbilityMatch;
     /**
      * List of rules
      */
-    rules: AbilityRule[];
+    rules: AbilityRule<Resources, Environment>[];
     /**
      * Rules compare method.\
      * For the «and» method the rule will be permitted if all\
@@ -34,13 +35,15 @@ export declare class AbilityRuleSet<Resources extends object = object> {
      */
     id: string;
     constructor(params: AbilityRuleSetConstructorProps);
-    addRule(rule: AbilityRule): this;
-    addRules(rules: AbilityRule[]): this;
-    check(resources: Resources | null): AbilityMatch;
+    addRule(rule: AbilityRule<Resources, Environment>): this;
+    addRules(rules: AbilityRule<Resources, Environment>[]): this;
+    check(resources: Resources | null, environment?: Environment): Promise<AbilityMatch>;
+    toString(): string;
     /**
      * Parse the config JSON format to Group class instance
      */
-    static parse<Resource extends object = object>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource>;
-    export(): AbilityRuleSetConfig;
+    static fromJSON<Resource extends ResourceObject = Record<string, unknown>, Environment = unknown>(config: AbilityRuleSetConfig): AbilityRuleSet<Resource, Environment>;
+    static and(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
+    static or(rules: AbilityRule[]): AbilityRuleSet<Record<string, unknown>, unknown>;
 }
 export default AbilityRuleSet;

package/dist/index.d.ts

@@ -1,11 +1,19 @@
-export * from './AbilityCode';
-export * from './AbilityCompare';
-export * from './AbilityCondition';
-export * from './AbilityError';
-export * from './AbilityMatch';
-export * from './AbilityParser';
-export * from './AbilityPolicy';
-export * from './AbilityPolicyEffect';
-export * from './AbilityResolver';
-export * from './AbilityRule';
-export * from './AbilityRuleSet';
+export * from './core/AbilityCode';
+export * from './core/AbilityCompare';
+export * from './core/AbilityCondition';
+export * from './core/AbilityError';
+export * from './core/AbilityMatch';
+export * from './core/AbilityParser';
+export * from './core/AbilityPolicy';
+export * from './core/AbilityPolicyEffect';
+export * from './core/AbilityResolver';
+export * from './core/AbilityRule';
+export * from './core/AbilityRuleSet';
+export * from './core/AbilityExplain';
+export * from './core/AbilityResult';
+export * from './cache/AbilityCacheAdapter';
+export * from './cache/AbilityInMemoryCache';
+export * from './parsers/json/AbilityJSONParser';
+export * from './parsers/dsl/AbilityDSLParser';
+export * from './parsers/dsl/AbilityDSLLexer';
+export * from './parsers/dsl/AbilityDSLToken';