Ricardo f902ccbecb 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>

2026-08-18 06:05:03 -03:00

3.4 KiB

Raw Blame History

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:

{
  "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.

3.4 KiB Raw Blame History