@shield-acl/core/dist/index.d.ts

Sistema ACL (Access Control List) inteligente e granular com algoritmos de permissões

/**
 * Sistema de ACL (Access Control List) inteligente e granular
 * Suporta permissões simples, com recursos, condições e wildcards
 */
type PermissionAction = string;
type ResourceType = string;
type RoleName = string;
/**
 * Condição dinâmica para avaliar permissões
 * Recebe contexto e retorna boolean
 */
type PermissionCondition<TContext = any> = (context: TContext) => boolean;
/**
 * Permissão básica do sistema
 */
interface Permission<TContext = any> {
    action: PermissionAction;
    resource?: ResourceType;
    conditions?: PermissionCondition<TContext>[];
    deny?: boolean;
}
/**
 * Regra de permissão com suporte a wildcards e patterns
 */
interface PermissionRule<TContext = any> {
    action: PermissionAction | PermissionAction[];
    resource?: ResourceType | ResourceType[];
    conditions?: PermissionCondition<TContext>[];
    deny?: boolean;
    priority?: number;
}
/**
 * Role (papel) que agrupa múltiplas permissões
 */
interface Role<TContext = any> {
    name: RoleName;
    permissions: PermissionRule<TContext>[];
    inherits?: RoleName[];
}
/**
 * Usuário com roles e permissões diretas
 */
interface User<TContext = any> {
    id: string | number;
    roles: RoleName[];
    permissions?: PermissionRule<TContext>[];
    attributes?: Record<string, any>;
}
/**
 * Contexto de avaliação de permissão
 */
interface EvaluationContext<TResource = any> {
    user: User;
    resource?: TResource;
    metadata?: Record<string, any>;
}
/**
 * Resultado da avaliação de permissão
 */
interface EvaluationResult {
    allowed: boolean;
    reason?: string;
    matchedRule?: PermissionRule;
}
/**
 * Opções de configuração do ACL
 */
interface ACLConfig {
    wildcardPattern?: string;
    caseSensitive?: boolean;
    cache?: boolean;
    cacheMaxSize?: number;
    cacheTTL?: number;
    defaultDeny?: boolean;
    debug?: boolean;
}
/**
 * Interface principal do motor ACL
 */
interface ACLEngine<TContext = any> {
    defineRole(role: Role<TContext>): void;
    removeRole(name: RoleName): void;
    getRole(name: RoleName): Role<TContext> | undefined;
    can(user: User<TContext>, action: PermissionAction, resource?: ResourceType, context?: TContext): boolean;
    evaluate(user: User<TContext>, action: PermissionAction, resource?: ResourceType, context?: TContext): EvaluationResult;
    getUserPermissions(user: User<TContext>): PermissionRule<TContext>[];
    getRoleHierarchy(roleName: RoleName): RoleName[];
    clearCache(): void;
}
/**
 * Tipos utilitários para patterns e wildcards
 */
type PatternMatcher = (pattern: string, value: string) => boolean;
interface CacheEntry {
    key: string;
    result: EvaluationResult;
    timestamp: number;
}
/**
 * Tipos para facilitar definições
 */
type PermissionMap = Record<PermissionAction, ResourceType[] | boolean>;
type RoleDefinition<TContext = any> = Omit<Role<TContext>, "permissions"> & {
    permissions: (PermissionRule<TContext> | string)[];
};
/**
 * Helpers para criação de permissões
 */
interface PermissionBuilder<TContext = any> {
    action(action: PermissionAction): this;
    resource(resource: ResourceType): this;
    when(condition: PermissionCondition<TContext>): this;
    deny(): this;
    build(): PermissionRule<TContext>;
}

/**
 * Motor ACL inteligente com suporte a wildcards, cache e herança
 */
declare class ACL<TContext = any> implements ACLEngine<TContext> {
    private roles;
    private cache;
    private config;
    private patternMatcher;
    constructor(config?: ACLConfig);
    /**
     * Cria um matcher de patterns com suporte a wildcards
     */
    private createPatternMatcher;
    /**
     * Define uma role no sistema
     */
    defineRole(role: Role<TContext>): void;
    /**
     * Remove uma role do sistema
     */
    removeRole(name: RoleName): void;
    /**
     * Obtém uma role pelo nome
     */
    getRole(name: RoleName): Role<TContext> | undefined;
    /**
     * Verifica se usuário tem permissão
     */
    can(user: User<TContext>, action: PermissionAction, resource?: ResourceType, context?: TContext): boolean;
    /**
     * Avalia permissão com detalhes
     */
    evaluate(user: User<TContext>, action: PermissionAction, resource?: ResourceType, context?: TContext): EvaluationResult;
    /**
     * Obtém todas as permissões de um usuário (incluindo roles)
     */
    getUserPermissions(user: User<TContext>): PermissionRule<TContext>[];
    /**
     * Coleta permissões de uma role recursivamente (herança)
     */
    private collectRolePermissions;
    /**
     * Obtém hierarquia completa de uma role
     */
    getRoleHierarchy(roleName: RoleName): RoleName[];
    /**
     * Verifica se uma permissão corresponde à ação/recurso
     */
    private matchesPermission;
    /**
     * Ordena permissões por prioridade e especificidade
     */
    private sortPermissions;
    /**
     * Calcula especificidade de uma regra (mais alto = mais específico)
     */
    private calculateSpecificity;
    /**
     * Formata regra para mensagem
     */
    private formatRule;
    /**
     * Verifica cache
     */
    private checkCache;
    /**
     * Salva no cache
     */
    private saveToCache;
    /**
     * Gera chave de cache
     */
    private getCacheKey;
    /**
     * Gera hash simples do contexto para cache
     */
    private hashContext;
    /**
     * Limpa todo o cache
     */
    clearCache(): void;
}
/**
 * Factory function para criar instância ACL
 */
declare function createACL<TContext = any>(config?: ACLConfig): ACL<TContext>;

/**
 * Builder fluente para criar permissões
 */
declare class PermissionRuleBuilder<TContext = any> implements PermissionBuilder<TContext> {
    private rule;
    action(action: string): this;
    resource(resource: string): this;
    when(condition: PermissionCondition<TContext>): this;
    deny(): this;
    priority(value: number): this;
    build(): PermissionRule<TContext>;
}
/**
 * Factory para criar builder de permissão
 */
declare function permission<TContext = any>(): PermissionBuilder<TContext>;
/**
 * Helpers para criar permissões comuns rapidamente
 */
declare const permissions: {
    crud: (resource: string) => {
        action: string;
        resource: string;
    }[];
    all: (resource: string) => {
        action: string;
        resource: string;
    };
    readonly: (resource: string) => {
        action: string;
        resource: string;
    }[];
    write: (resource: string) => {
        action: string;
        resource: string;
    }[];
    manage: (resource: string) => {
        action: string;
        resource: string;
    };
};
/**
 * Helper para criar condições comuns
 */
declare const conditions: {
    isOwner: <T extends {
        userId?: any;
        ownerId?: any;
    }>(userIdField?: string) => PermissionCondition<{
        user: {
            id: any;
        };
        resource: T;
    }>;
    hasStatus: <T extends {
        status?: string;
    }>(...statuses: string[]) => PermissionCondition<{
        resource: T;
    }>;
    userHasAttribute: (attribute: string, value?: any) => PermissionCondition<{
        user: {
            attributes?: Record<string, any>;
        };
    }>;
    createdWithin: <T extends {
        createdAt?: Date | string;
    }>(milliseconds: number) => PermissionCondition<{
        resource: T;
    }>;
    and: <TContext>(...conditions: PermissionCondition<TContext>[]) => PermissionCondition<TContext>;
    or: <TContext>(...conditions: PermissionCondition<TContext>[]) => PermissionCondition<TContext>;
    not: <TContext>(condition: PermissionCondition<TContext>) => PermissionCondition<TContext>;
};

/**
 * Roles predefinidas comuns que podem ser usadas como base
 */
declare const rolePresets: {
    /**
     * Super administrador - acesso total
     */
    superAdmin: () => Role;
    /**
     * Administrador - gerencia tudo exceto configurações críticas
     */
    admin: () => Role;
    /**
     * Moderador - pode moderar conteúdo
     */
    moderator: () => Role;
    /**
     * Editor - pode criar e editar conteúdo
     */
    editor: () => Role;
    /**
     * Autor - pode gerenciar apenas seu próprio conteúdo
     */
    author: <TContext = any>() => Role<TContext>;
    /**
     * Usuário autenticado básico
     */
    user: <TContext = any>() => Role<TContext>;
    /**
     * Visitante - acesso apenas leitura
     */
    guest: () => Role;
};
/**
 * Permissões predefinidas para recursos comuns
 */
declare const resourcePermissions: {
    /**
     * Blog/CMS
     */
    blog: {
        posts: {
            action: string;
            resource: string;
        }[];
        pages: {
            action: string;
            resource: string;
        }[];
        comments: {
            action: string;
            resource: string;
        }[];
        media: {
            action: string;
            resource: string;
        }[];
        categories: {
            action: string;
            resource: string;
        }[];
        tags: {
            action: string;
            resource: string;
        }[];
    };
    /**
     * E-commerce
     */
    ecommerce: {
        products: {
            action: string;
            resource: string;
        }[];
        orders: {
            action: string;
            resource: string;
        }[];
        customers: {
            action: string;
            resource: string;
        }[];
        inventory: {
            action: string;
            resource: string;
        }[];
        coupons: {
            action: string;
            resource: string;
        }[];
        shipping: {
            action: string;
            resource: string;
        }[];
    };
    /**
     * SaaS
     */
    saas: {
        organizations: {
            action: string;
            resource: string;
        }[];
        projects: {
            action: string;
            resource: string;
        }[];
        teams: {
            action: string;
            resource: string;
        }[];
        members: {
            action: string;
            resource: string;
        }[];
        billing: {
            action: string;
            resource: string;
        }[];
        subscriptions: {
            action: string;
            resource: string;
        }[];
    };
    /**
     * Social
     */
    social: {
        posts: {
            action: string;
            resource: string;
        }[];
        friends: {
            action: string;
            resource: string;
        }[];
        messages: {
            action: string;
            resource: string;
        }[];
        groups: {
            action: string;
            resource: string;
        }[];
        events: {
            action: string;
            resource: string;
        }[];
        notifications: {
            action: string;
            resource: string;
        }[];
    };
};
/**
 * Helpers para criar estruturas de permissão comuns
 */
declare const permissionPatterns: {
    /**
     * Padrão de propriedade - usuário só pode modificar seus próprios recursos
     */
    ownership: <TContext extends {
        user: {
            id: any;
        };
        resource?: {
            [key: string]: any;
        };
    }>(resource: string, ownerField?: string) => PermissionRule<TContext>[];
    /**
     * Padrão de colaboração - múltiplos níveis de acesso
     */
    collaboration: (resource: string) => PermissionRule[];
    /**
     * Padrão de workflow - permissões baseadas em status
     */
    workflow: (resource: string, workflow: Record<string, string[]>) => PermissionRule[];
};

export { ACL, type ACLConfig, type ACLEngine, type CacheEntry, type EvaluationContext, type EvaluationResult, type PatternMatcher, type Permission, type PermissionAction, type PermissionBuilder, type PermissionCondition, type PermissionMap, type PermissionRule, PermissionRuleBuilder, type ResourceType, type Role, type RoleDefinition, type RoleName, type User, conditions, createACL, permission, permissionPatterns, permissions, resourcePermissions, rolePresets };