# 🔐 Documentação da API: Entrega Protegida de Arquivos (`api/arquivos`)

Este módulo substitui qualquer acesso direto à pasta `/uploads` no servidor. Todos os links retornados pela API (`url_arquivo`, `url_foto_perfil`, `url_contrato_minuta`, `url_contrato_assinado`, `url_comprovante`, `url_foto`, `url_completa`, `foto_capa_url`) apontam para `ver.php` com **token temporário assinado via HMAC-SHA256**.

---

## 1. Visualizar ou Baixar Arquivo (`ver.php`)

- **URL Base:** `GET /aluguel/api/arquivos/ver.php`
- **Validade padrão do link assinado:** **15 minutos** (`FILE_URL_TTL_SECONDS = 900` em `api/config/config.php`)

### Forma 1: Token Temporário na URL *(gerado automaticamente pela API)*
Ideal para `<img src="...">`, `<a href="...">`, WebView mobile ou visualizadores de PDF sem precisar passar o token de login na URL.

```text
GET /aluguel/api/arquivos/ver.php?arquivo=documentos/9a1b2c..._1762890000.pdf&expires=1794443200&uid=2&token=a4f9...hmac...
```

O servidor valida em **4 camadas** antes de enviar o arquivo:
1. Confere assinatura **HMAC-SHA256** (`arquivo | expires | uid`) usando `hash_equals` e `FILE_SIGNING_SECRET`.
2. Confere se o prazo `expires` ainda não venceu (`401` se expirado).
3. Consulta o MySQL em tempo real para confirmar que `uid` ainda possui vínculo ou posse sobre aquele arquivo específico (`403` se negado).
4. Bloqueia qualquer tentativa de *path traversal* (`../`) e entrega apenas arquivos reais dentro das pastas permitidas (`documentos`, `perfis`, `comprovantes`, `vistorias`, `imoveis`).

> **Importante:** Arquivos privados (`documentos/`, `perfis/`, `comprovantes/`, `vistorias/`) **nunca** são entregues para `uid=0`. Apenas imagens de capa públicas (`imoveis/`) cadastradas no catálogo aceitam `uid=0`.

---

### Forma 2: Chamada Autenticada via Header `Authorization: Bearer`
Caso o app ou frontend queira buscar o binário via `fetch` / `Blob` sem depender da URL assinada:

```http
GET /aluguel/api/arquivos/ver.php?arquivo=documentos/9a1b2c..._1762890000.pdf
Authorization: Bearer <SEU_TOKEN_DE_SESSAO>
```

---

## 2. Parâmetro Opcional de Download Forçado

Adicione `&download=1` ao final da URL caso queira forçar `Content-Disposition: attachment` no navegador em vez de abrir inline:

```text
GET /aluguel/api/arquivos/ver.php?arquivo=...&expires=...&uid=...&token=...&download=1
```

---

## 3. Produção com Múltiplos Servidores / Containers

Para manter as assinaturas consistentes em ambientes com balanceamento de carga ou múltiplos workers, configure a variável de ambiente **`APP_FILE_SECRET`** com uma chave aleatória forte de pelo menos 32 caracteres. Caso não esteja definida, o sistema gera automaticamente uma chave criptográfica aleatória exclusiva por instalação em `uploads/.signing.key` (protegida contra leitura via HTTP).