# Permissões ACL por pasta

A versão 0.8.0 introduz controlo de acesso por dossiê, pasta, utilizador, grupo e role. A autorização é executada no servidor; esconder botões na interface nunca substitui a verificação no controller ou serviço.

## Permissões

| Código | Ação protegida |
|---|---|
| `view` | Abrir o dossiê/pasta, listar documentos e consultar registos associados |
| `download` | Descarregar documentos, PDFs gerados, PDFs assinados e evidências |
| `upload` | Carregar documentos e arquivar PDFs gerados |
| `create_subfolder` | Criar pastas abaixo da localização |
| `rename` | Renomear uma pasta; a movimentação exige também `manage_acl` na origem e no destino |
| `delete` | Apagar documentos, pastas vazias ou dossiês vazios |
| `share` | Criar links temporários, pedidos de assinatura, anexos e públicos de comunicação |
| `manage_acl` | Criar/remover regras e alterar a herança |

## Principais

Uma regra pode ser atribuída a:

- todos os membros ativos da organização;
- um role (`owner`, `admin`, `editor`, `member` ou `viewer`);
- um grupo ACL;
- um utilizador específico.

Os grupos ACL pertencem exclusivamente a uma organização e só aceitam membros ativos dessa organização.

## Herança

A raiz do dossiê funciona como a primeira localização ACL. Por defeito, uma pasta herda regras da raiz e de todas as pastas superiores.

Ao interromper a herança numa pasta:

- as regras da raiz e dos antepassados deixam de ser consideradas;
- as regras diretas da própria pasta continuam ativas;
- as permissões base do role continuam a aplicar-se;
- uma negação direta pode remover uma permissão base.

Os filhos continuam a herdar dessa pasta, salvo se também interromperem a herança.

## Precedência

1. superadministradores, proprietários e administradores da organização têm acesso de recuperação integral;
2. todas as regras aplicáveis são recolhidas através da cadeia de herança;
3. uma negação aplicável prevalece sobre qualquer concessão;
4. se não existir negação, uma concessão explícita prevalece sobre a permissão base;
5. na ausência de regras, aplica-se a permissão base do role.

Esta regra impede que uma concessão ampla anule acidentalmente uma pasta explicitamente bloqueada.

## Permissões base

- `owner` e `admin`: todas as permissões;
- `editor`: ver, descarregar, carregar, criar subpastas, renomear, eliminar e partilhar;
- `member` e `viewer`: ver e descarregar.

As permissões base podem ser alteradas em `config/acl.php`. Depois de alterar a configuração, execute `php artisan optimize:clear`.


## Movimentação de pastas

Renomear sem mudar a localização exige apenas `rename`. Mover uma pasta altera os antepassados cujas regras são herdadas e pode modificar o acesso a toda a subárvore. Por esse motivo, uma movimentação exige:

- `rename` na pasta de origem;
- `manage_acl` na pasta de origem;
- `manage_acl` no destino;
- `create_subfolder` no destino.

A aplicação recalcula os caminhos dos descendentes e incrementa a versão ACL da organização.

## Operações protegidas

A ACL é aplicada a:

- listagem e abertura de dossiês;
- árvore de pastas e contagem visível de documentos;
- upload, download e remoção de documentos;
- criação, renomeação, movimentação e eliminação de pastas;
- criação de links públicos;
- escolha de anexos e dossiês nas comunicações;
- consulta, exportação, pausa, retoma, cancelamento e repetição de lotes apenas enquanto o respetivo público e anexos permanecerem autorizados;
- geração, consulta e download de PDFs;
- criação, consulta e download de pedidos de assinatura;
- relatórios de pedidos pendentes;
- métricas e listagens do dashboard.

Os links públicos já emitidos continuam a utilizar o seu token, validade e limites próprios. A ACL é verificada no momento em que o utilizador interno cria a partilha.

## Cache e invalidação

As decisões são guardadas por um período curto. A chave inclui:

- organização;
- versão ACL da organização;
- utilizador;
- dossiê e pasta;
- permissão.

Criar ou remover regras, alterar grupos, mover pastas ou mudar a herança incrementa `tenants.acl_version`, invalidando imediatamente decisões antigas sem depender de cache tags.

```dotenv
ACL_CACHE_SECONDS=300
```

## Recuperação e prevenção de bloqueios

As negações não bloqueiam superadministradores, proprietários nem administradores. Assim, existe sempre uma conta capaz de corrigir uma configuração incorreta.

A gestão dos grupos está limitada a `owner` e `admin`. A gestão de regras pode ser delegada através de `manage_acl`, sem permitir alterar os grupos globais da organização.

## Auditoria

São registados os eventos:

- `folder_acl.entry_created`;
- `folder_acl.entry_deleted`;
- `folder_acl.inheritance_changed`;
- `folder_acl.group_created`;
- `folder_acl.group_updated`;
- `folder_acl.group_deleted`;
- `folder.updated` quando uma alteração muda a cadeia de herança.

## Atualização

```bash
composer install
php artisan migrate --force
php artisan optimize:clear
php artisan queue:restart
```

As pastas existentes começam com `acl_inherits = true`. Como ainda não têm regras diretas, mantêm o comportamento compatível com as permissões base dos roles.