@shield-acl/core/README.md

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

# @shield-acl/core

<div align="center">
  <img src="https://raw.githubusercontent.com/andersondrosa/andersondrosa/refs/heads/main/images/shield-acl.png" alt="Shield ACL Core" width="400" />
</div>

<div align="center">
  <p><strong>Motor de ACL inteligente e granular com algoritmos otimizados</strong></p>
  <p>Biblioteca puramente funcional sem dependências de framework.</p>
</div>

## 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

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

## Uso Básico

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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

```typescript
const acl = new ACL(config?: ACLConfig)
```

Configurações disponíveis:

```typescript
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:

```typescript
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:

```typescript
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

```bash
# Rodar testes
pnpm test

# Coverage
pnpm test:coverage

# Watch mode
pnpm test:watch
```

## Documentação Adicional

- [Algoritmo ACL Detalhado](./docs/ACL-ALGORITHM.md) - Documentação técnica completa do algoritmo
- [Funcionamento Interno](./docs/FUNCIONAMENTO.md) - Explicação detalhada da lógica interna

## Licença

MIT © Anderson D. Rosa