Conector Scardua — recebe da API da FLS e entrega no Oracle do cliente

Servico que roda dentro da rede da Comercial Scardua e faz a ponte entre a
API publica da FLS (na VPS) e o Oracle privado (10.16.x), inalcancavel pela
internet.

Fluxo: Holmes -> API na VPS (trata e cifra) -> ESTE conector (abre e valida)
-> Oracle.

Recebimento:
- app/v1/compras.py: POST /v1/compras/dados
- app/services/cripto.py: abre o envelope AES-256-GCM + RSA-OAEP-SHA256 com a
  chave privada. O GCM autentica: corpo adulterado levanta InvalidTag em vez
  de devolver lixo
- app/schemas.py: modulo folha (so pydantic) com a config e o contrato
  PayloadCompras, que espelha o da API. Fora de sincronia devolve 422 de
  proposito, pra falhar explicito em vez de gravar dado torto

Seguranca:
- app/seguranca.py: header X-Token com compare_digest (nao vaza por tempo de
  resposta) + allowlist de IP da VPS
- .gitignore barra configs.json.*, *.bak-*, *.pem e *.key

Config:
- app/config.py e so o carregamento do configs.json
- o bloco "vps" guarda chave privada, token e ips permitidos

Estado: ainda NAO persiste. Recebe, valida e descarta (persistido: false).
O INSERT no Oracle e a proxima fase, e tem que ser MERGE por id_processo
porque o Holmes reentrega webhook.

Docs em docs/ — arquitetura, a decisao do conector (opcao A, com as
alternativas descartadas), deploy e problemas conhecidos.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/conector.md

@@ -0,0 +1,81 @@
+# Conector com o cliente — decisão FECHADA
+
+> Este doc guardava as opções em aberto. A decisão foi tomada: **opção A**.
+> Ficam registradas as alternativas e o porquê da escolha.
+
+## O problema
+
+O Oracle da Scardua está em **rede privada** (`10.16.x`), inalcançável da
+internet. A API roda na VPS da FLS (pública). Algo precisa rodar as queries no
+Oracle **de dentro** da rede do cliente. Esse algo é este projeto.
+
+## A decisão: opção A — conector que RECEBE
+
+Direção **VPS → conector**. A API trata o dado, cifra e faz `POST` aqui; o
+conector abre e grava no Oracle.
+
+- ✅ A VPS **não armazena nada** — é passagem
+- ✅ Simples: recebe e insere
+- ⚠️ O conector fica **exposto** — mitigado pelas travas abaixo
+
+### As alternativas descartadas
+
+**B) Conector outbound (pull)** — o conector perguntaria pra VPS "tem trabalho?".
+Sem rota pública no cliente, mais firewall-friendly. Descartada porque exigiria a
+VPS manter fila de pendências (storage que ela não tem) e mais lógica de polling.
+
+**C) Túnel / VPN** — a VPS alcançaria o Oracle direto. Descartada porque poria a
+senha do Oracle na VPS e daria acesso **amplo** à rede do cliente.
+
+## Travas de segurança (implementadas)
+
+Um endpoint público que escreve no banco de produção é alvo de alto valor. O que
+está no código hoje:
+
+| Trava | Onde | Estado |
+|---|---|---|
+| **TLS** | proxy na frente do conector | ⬜ depende da publicação |
+| **Token compartilhado** — header `X-Token`, comparado com `secrets.compare_digest` (não vaza por tempo) | `app/seguranca.py` | ✅ |
+| **Allowlist de IP** — só a VPS (`179.197.230.154`) | `app/seguranca.py` + `configs.json` | ✅ (vazio = desligado, ligar em produção) |
+| **Payload cifrado ponta a ponta** | `app/services/cripto.py` | ✅ |
+| **Validação de schema** | `PayloadCompras` em `app/schemas.py` | ✅ |
+| **Usuário Oracle de privilégio mínimo** | — | ⬜ fase 4 |
+| **Rate limiting** | — | ⬜ |
+
+## A criptografia
+
+Envelope híbrido — **AES-256-GCM** nos dados, **RSA-OAEP-SHA256** na chave AES:
+
+```json
+{
+  "alg":   "RSA-OAEP-256+A256GCM",
+  "chave": "<chave AES cifrada com a pública do conector, base64>",
+  "nonce": "<nonce do GCM, base64>",
+  "dados": "<JSON cifrado + tag de autenticação, base64>"
+}
+```
+
+**Por que não RSA puro:** RSA-2048 com OAEP-SHA256 cifra no máximo ~190 bytes, e
+o payload de compras passa disso. Envelope é o padrão (mesmo do TLS, PGP e JWE).
+
+**O GCM autentica:** se o corpo for adulterado no caminho, o decrypt levanta
+`InvalidTag` em vez de devolver lixo. Decifrou = veio íntegro.
+
+**As chaves:** a **privada** fica só aqui, no `configs.json` (gitignored). A
+**pública** correspondente vai no `configs.json` da VPS. Hoje é um par de
+**homologação** — trocar por um definitivo antes de produção.
+
+## Idempotência ⭐
+
+O Holmes reentrega webhook. O `id_processo` (id do processo no Holmes) viaja no
+payload justamente pra ser a chave de deduplicação. Quando o `INSERT` entrar,
+**tem que ser `MERGE`** — senão cada reentrega vira linha duplicada.
+
+## Durabilidade
+
+Escolhido: **erro sobe, Holmes reentrega.** O conector fora do ar → a API devolve
+erro → o Holmes reenvia depois. O Holmes é a fila; por isso a API **nunca** pode
+responder 200 pra algo que não chegou aqui.
+
+⚠️ Depende da política de retry do Holmes, que **ainda não foi confirmada**. Se
+ele não reentregar, vai ser preciso persistência intermediária na VPS.