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

2.9 KiB

Raw Blame History

Deploy — Conector Scardua

⚠️ O runbook da VPS da FLS (Podman/Quadlet/Caddy, api-scardua.flstecnologia.tech) saiu daqui — ele pertence ao repositório da API. Este doc é do conector, que roda no servidor da Scardua.

Onde ele roda

No servidor do cliente, com acesso à rede privada 10.16.x onde está o Oracle. Precisa ser alcançável pela VPS (179.197.230.154) — é a VPS que faz o POST.

Pré-requisitos

Item	Detalhe
Python	≥3.10, ou Podman/Docker se for containerizado
Rede	porta de entrada liberada só pro IP da VPS
TLS	proxy na frente (Caddy/nginx) — a VPS manda payload financeiro
Oracle	usuário de privilégio mínimo: só `INSERT`/`MERGE` nas tabelas do fluxo

configs.json

Nunca versionado. Ver configs.example.json. Os campos críticos:

"vps": {
    "chave_privada": "-----BEGIN PRIVATE KEY-----\n...",
    "token": "<segredo compartilhado com a VPS>",
    "ips_permitidos": ["179.197.230.154"]
}

chave_privada — o segredo mais sensível do projeto. Quem tem ela lê todo payload. Permissão 600, nunca em repo, nunca em imagem.
token — tem que ser o mesmo configurado na VPS (header X-Token).
ips_permitidos — deixar vazio só em teste local. Em produção, preencher.

As chaves

Par RSA-2048. A privada fica aqui; a pública vai no configs.json da VPS. Para gerar um par novo:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out privada.pem
openssl rsa -in privada.pem -pubout -out publica.pem

O par em uso hoje é de homologação — trocar antes de produção, e trocar os dois lados juntos (senão a VPS cifra com uma pública que este conector não abre).

Subir

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2

Se for container, o Dockerfile da raiz serve — mas o configs.json tem que ser montado por volume, nunca copiado pra imagem (o .dockerignore já barra).

podman build --format docker -t conector-scardua:latest .

⚠️ --format docker é obrigatório: no formato OCI (padrão do Podman) o HEALTHCHECK do Dockerfile é silenciosamente ignorado.

Verificar que está de pé

curl -s http://localhost:8000/health           # -> {"status":"ok"}

E o caminho real, com o token:

curl -X POST http://localhost:8000/v1/compras/dados \
  -H "X-Token: <o token do configs.json>" \
  -H "Content-Type: application/json" \
  -d '<envelope gerado pela API da VPS>'

Respostas esperadas: 200 recebido · 401 token errado · 403 IP fora da allowlist · 400 envelope não abriu (chave errada ou adulterado) · 422 payload fora do contrato.

Comandos úteis

journalctl -u conector-scardua -f       # se rodar via systemd
podman logs -f conector-scardua         # se rodar em container

2.9 KiB Raw Blame History