@shield-acl/core v1.0.0

@shield-acl/core

Características

• 🎯 Granular: Controle fino de permissões com ações, recursos e condições
• 🔐 Seguro: Deny by default, com negação explícita
• 🚀 Performático: Cache inteligente e otimizações de avaliação
• 🧩 Extensível: Sistema de plugins e condições customizadas
• 🌳 Hierárquico: Herança de roles e composição de permissões
• ⚡ TypeScript: Totalmente tipado com IntelliSense completo
• 🎪 Sem dependências: Algoritmos puros sem dependências externas

Instalação

npm install @shield-acl/core
# ou
yarn add @shield-acl/core
# ou
pnpm add @shield-acl/core

Uso Básico

import { ACL } from '@shield-acl/core'

// 1. Criar instância do ACL
const acl = new ACL()

// 2. Definir roles
acl.defineRole({
  name: 'admin',
  permissions: [
    { action: '*', resource: '*' } // Admin pode tudo
  ]
})

acl.defineRole({
  name: 'user',
  permissions: [
    { action: 'read', resource: 'posts' },
    { 
      action: ['update', 'delete'], 
      resource: 'posts',
      conditions: [(ctx) => ctx.resource?.authorId === ctx.user.id]
    }
  ]
})

// 3. Criar usuário
const user = {
  id: 1,
  roles: ['user'],
  permissions: [
    { action: 'create', resource: 'comments' } // Permissão direta
  ]
}

// 4. Verificar permissões
const canRead = acl.can(user, 'read', 'posts') // true
const canDelete = acl.can(user, 'delete', 'posts', {
  resource: { authorId: 1 }
}) // true (é o autor)

const canDeleteOthers = acl.can(user, 'delete', 'posts', {
  resource: { authorId: 2 }
}) // false (não é o autor)

Algoritmos e Conceitos

1. Avaliação de Permissões

O algoritmo de avaliação segue esta ordem de prioridade:

1. Negações explícitas (deny) têm prioridade máxima
2. Permissões diretas do usuário sobrescrevem roles
3. Permissões das roles (com suporte a herança)
4. Default deny se nenhuma regra permitir

2. Pattern Matching

Suporte completo a wildcards e patterns:

// Wildcards simples
{ action: 'posts.*' } // Qualquer ação em posts
{ action: '*.read' } // Leitura em qualquer recurso
{ action: '*', resource: 'admin/*' } // Qualquer ação em recursos admin

// Arrays de permissões
{ action: ['create', 'read', 'update'], resource: 'posts' }

// Negação explícita
{ action: 'delete', resource: 'users', deny: true }

3. Condições Dinâmicas

Avaliação condicional baseada em contexto:

const ownerCondition = (ctx) => ctx.resource?.ownerId === ctx.user.id
const publishedCondition = (ctx) => ctx.resource?.status === 'published'

acl.defineRole({
  name: 'author',
  permissions: [{
    action: 'edit',
    resource: 'posts',
    conditions: [ownerCondition] // Só pode editar próprios posts
  }]
})

4. Herança de Roles

Sistema hierárquico com herança múltipla:

acl.defineRole({
  name: 'moderator',
  inherits: ['user'], // Herda permissões de user
  permissions: [
    { action: 'moderate', resource: 'comments' },
    { action: 'ban', resource: 'users' }
  ]
})

acl.defineRole({
  name: 'admin',
  inherits: ['moderator'], // Herda de moderator (e user)
  permissions: [
    { action: '*', resource: '*' }
  ]
})

API Completa

ACL Class

const acl = new ACL(config?: ACLConfig)

Configurações disponíveis:

interface ACLConfig {
  wildcardPattern?: string    // Default: "*"
  caseSensitive?: boolean     // Default: false
  cache?: boolean            // Default: true
  cacheMaxSize?: number      // Default: 1000
  cacheTTL?: number          // Default: 300000 (5 min)
  defaultDeny?: boolean      // Default: true
  debug?: boolean            // Default: false
}

Métodos Principais

defineRole(role: Role): void

Define uma nova role no sistema.

can(user: User, action: string, resource?: string, context?: any): boolean

Verifica se o usuário tem permissão para executar a ação.

evaluate(user: User, action: string, resource?: string, context?: any): EvaluationResult

Retorna resultado detalhado da avaliação com motivo.

getUserPermissions(user: User): PermissionRule[]

Obtém todas as permissões efetivas do usuário.

getRoleHierarchy(roleName: string): string[]

Retorna a hierarquia completa de uma role.

clearCache(): void

Limpa o cache de avaliações.

Helpers e Utilities

Permission Builder

API fluente para criar permissões:

import { permission } from '@shield-acl/core'

const perm = permission()
  .action('posts.write')
  .resource('posts')
  .when((ctx) => ctx.user.verified)
  .build()

Presets

Conjuntos de permissões pré-definidos:

import { presets } from '@shield-acl/core'

// CRUD completo
const crudPosts = presets.crud('posts')
// Gera: create, read, update, delete para posts

// Somente leitura
const readOnly = presets.readonly(['posts', 'comments'])
// Gera: read para posts e comments

// Moderação
const modPerms = presets.moderation(['comments', 'posts'])
// Gera: approve, reject, flag para os recursos

Performance

Cache Inteligente

O sistema implementa cache LRU com TTL configurável:

• Avaliações idênticas são cacheadas
• Cache key baseado em: user.id + action + resource + context hash
• Invalidação automática ao modificar roles
• Limite configurável de entradas

Otimizações

1. Early termination: Para ao encontrar deny explícito
2. Pattern compilation: Regex compilados e cacheados
3. Hierarchy memoization: Hierarquia de roles calculada uma vez
4. Batch evaluation: Suporte para verificar múltiplas permissões

Testes

# Rodar testes
pnpm test

# Coverage
pnpm test:coverage

# Watch mode
pnpm test:watch

Documentação Adicional

• Algoritmo ACL Detalhado - Documentação técnica completa do algoritmo
• Funcionamento Interno - Explicação detalhada da lógica interna

Licença

MIT © Anderson D. Rosa