# Assinatura pública, OTP e aplicação visual

## Fluxo

1. Um utilizador `owner`, `admin` ou `editor` abre um PDF gerado que contenha regiões `signature` ou `initials`.
2. Cria um pedido, escolhe as regiões, destinatário, validade e opções de segurança.
3. A plataforma guarda apenas o SHA-256 do token e envia o link por email.
4. O destinatário abre o link e, por defeito, pede um OTP de utilização única.
5. Após validação, uma sessão pública curta e HttpOnly permite consultar o PDF privado.
6. O destinatário desenha, escreve ou carrega a assinatura, aceita o consentimento e submete.
7. A imagem é validada, o fundo quase branco é tornado transparente, o resultado é normalizado para PNG privado e ligado às regiões.
8. O worker `signatures` importa o PDF, aplica visualmente a assinatura e cria um novo documento imutável.
9. O documento original é marcado como `superseded`, o novo documento como `signed` e é gerado um ficheiro de evidência JSON.

Cada PDF admite um único pedido ativo de cada vez. Um pedido pode incluir várias regiões de assinatura ou rubrica para o mesmo destinatário. Esta regra impede a criação simultânea de versões finais divergentes do mesmo documento.

## Segurança implementada

- Tokens aleatórios de 384 bits e armazenamento exclusivo por hash SHA-256.
- Convites e OTP são enviados de forma síncrona para não persistir o token ou o código em claro no payload de uma fila.
- Rotação do token em cada reenvio; o link anterior deixa de funcionar.
- OTP configurável, guardado por HMAC, com expiração, cooldown, tentativas máximas e utilização única.
- Rate limiting independente para envio e validação de OTP.
- Sessão pública aleatória, HttpOnly, SameSite=Lax, com expiração curta e opção de vinculação ao user-agent/IP.
- PDF e assinaturas sempre em discos privados.
- Verificação SHA-256 do PDF original e de cada imagem antes da aplicação.
- Estado `processing` e bloqueio pessimista dos campos impedem submissões simultâneas/repetidas.
- Cadeia de eventos ligada por HMAC: cada evento contém o hash do evento anterior.
- Evidência JSON com checksums, consentimento, campos, datas, hashes de IP/user-agent, cadeia de eventos e HMAC do payload completo; o download administrativo é bloqueado se a verificação falhar.
- Cabeçalhos `no-store`, `no-referrer`, `noindex` e bloqueio de framing na página pública.
- O endereço público deixa de aceitar uma nova assinatura após `processing` ou `signed`.

## Natureza da assinatura

A implementação produz uma **assinatura eletrónica visual com evidências técnicas de acesso e consentimento**. Não aplica um certificado criptográfico qualificado, selo temporal qualificado ou assinatura PAdES. Esses níveis exigem integração posterior com um prestador de serviços de confiança e validação jurídica adequada ao país e caso de utilização.

## Filas e scheduler

```bash
php artisan queue:work --queue=signatures,pdf,default --tries=3 --timeout=300
php artisan signatures:maintain
```

O scheduler executa `signatures:maintain` de hora a hora para expirar pedidos e remover sessões/OTP antigos.

## Variáveis

Consulte o bloco `SIGNATURE_*` em `.env.example`.