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>
This commit is contained in:
Ricardo
commit
f902ccbecb
26 changed files with 1824 additions and 0 deletions
81
docs/arquitetura.md
Normal file
81
docs/arquitetura.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# Arquitetura e Visão — Conector Scardua
|
||||
|
||||
> Documento da **ideia**: o quê, o porquê e o roadmap. Salvo pra não reexplicar
|
||||
> toda sessão. Atualizar quando a visão evoluir.
|
||||
|
||||
## Em uma frase
|
||||
|
||||
O conector roda **dentro da rede da Scardua**, recebe da API da FLS o dado já
|
||||
tratado e cifrado, abre e grava no **Oracle privado** do cliente.
|
||||
|
||||
## Os atores
|
||||
|
||||
- **FLS Tecnologia (dev / nós)** — hospeda a **API** na própria VPS
|
||||
(`api-scardua.flstecnologia.tech`). Ela recebe o webhook do Holmes, trata e cifra.
|
||||
- **Comercial Scardua (cliente)** — tem a conta no **Holmes** e o **Oracle**
|
||||
(IP privado `10.16.x`, inalcançável pela internet). **Este conector roda no
|
||||
servidor dele.**
|
||||
- **Holmes** — SaaS de workflow de documentos; dispara o webhook pra API da FLS.
|
||||
|
||||
## O fluxo completo
|
||||
|
||||
```
|
||||
Holmes
|
||||
│ webhook (público, TLS)
|
||||
▼
|
||||
API na VPS da FLS ← repositório da API
|
||||
│ · valida o payload do Holmes
|
||||
│ · traduz pro contrato do cliente
|
||||
│ · CIFRA com a chave pública do conector
|
||||
│ POST + X-Token (público, TLS)
|
||||
▼
|
||||
CONECTOR no servidor da Scardua ← ESTE repositório
|
||||
│ · confere token e IP de origem
|
||||
│ · ABRE com a chave privada
|
||||
│ · valida o contrato
|
||||
│ · MERGE por id_processo
|
||||
▼
|
||||
Oracle 10.16.x (rede privada)
|
||||
```
|
||||
|
||||
## As decisões e o PORQUÊ
|
||||
|
||||
**Por que a API fica na VPS da FLS, e não no servidor do cliente:**
|
||||
|
||||
1. **O Holmes precisa de endpoint público e estável** pros webhooks. Damos isso
|
||||
nós, com domínio e TLS próprios — sem depender de o cliente ter.
|
||||
2. **O código Python fica sob nosso controle**, na nossa infra.
|
||||
|
||||
**Consequência técnica:** o Oracle está em rede privada, então a VPS **não
|
||||
alcança o banco direto**. Daí este conector — a ponte entre o público e o privado.
|
||||
|
||||
**Por que o payload vai cifrado ponta a ponta,** mesmo já tendo TLS: o conteúdo é
|
||||
financeiro (CNPJ, notas, parcelas, vencimentos). Cifrando com a chave pública do
|
||||
conector, só ele abre — nem proxy no caminho, nem log de corpo de requisição,
|
||||
nem quem tiver acesso à VPS consegue ler. Detalhes em [conector.md](conector.md).
|
||||
|
||||
**Por que `id_processo` viaja no payload:** o Holmes reentrega webhook. Sem chave
|
||||
de deduplicação, cada reentrega vira linha duplicada no Oracle.
|
||||
|
||||
## Estado atual
|
||||
|
||||
| # | Fase | Estado |
|
||||
|---|---|---|
|
||||
| 1 | **API na VPS** — recebe do Holmes, trata, cifra | ✅ no ar |
|
||||
| 2 | **Conector recebe** — token, decifra, valida, loga | ✅ feito |
|
||||
| 3 | **API envia** — `POST` da VPS pro conector (`app/services/api_cliente.py` lá) | ⬜ a fazer |
|
||||
| 4 | **Conector grava** — pool Oracle + `MERGE` por `id_processo` | ⬜ a fazer |
|
||||
| 5 | **CI/CD** — Forgejo Actions + registry + auto-update | ⬜ desenhado |
|
||||
|
||||
Hoje o dado chega, é validado e **descartado** (`persistido: false` na resposta).
|
||||
Serve pra homologar o circuito; não persiste nada ainda.
|
||||
|
||||
## Pontos em aberto
|
||||
|
||||
- **Onde o conector é publicado** — precisa ser alcançável pela VPS. Porta
|
||||
liberada no firewall da Scardua? Domínio? IP fixo?
|
||||
- **Política de retry do Holmes** — quantas vezes reentrega e em quais status.
|
||||
A estratégia atual (erro sobe → Holmes reenvia) depende disso; sem retry dele,
|
||||
vai ser preciso persistência intermediária.
|
||||
- **Usuário Oracle de privilégio mínimo** — só `INSERT`/`MERGE` nas tabelas do
|
||||
fluxo, nada de `SELECT` geral nem DDL.
|
||||
81
docs/conector.md
Normal file
81
docs/conector.md
Normal file
|
|
@ -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.
|
||||
91
docs/deploy.md
Normal file
91
docs/deploy.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
# 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:
|
||||
|
||||
```json
|
||||
"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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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).
|
||||
|
||||
```bash
|
||||
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é
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8000/health # -> {"status":"ok"}
|
||||
```
|
||||
|
||||
E o caminho real, com o token:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
journalctl -u conector-scardua -f # se rodar via systemd
|
||||
podman logs -f conector-scardua # se rodar em container
|
||||
```
|
||||
55
docs/known-issues.md
Normal file
55
docs/known-issues.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# Problemas conhecidos / TODO — Conector Scardua
|
||||
|
||||
## Bloqueadores da fase 4 (gravar no Oracle)
|
||||
|
||||
- **Não existe camada de conexão.** `app/infra/database.py` é referenciado por
|
||||
`app/security.py` mas **nunca existiu**. Nada abre pool no caminho que roda.
|
||||
- **O conector não persiste nada.** Hoje ele recebe, decifra, valida e **descarta**
|
||||
(responde `persistido: false`). O circuito está homologado; o `INSERT` não.
|
||||
- Quando o `INSERT` entrar, **tem que ser `MERGE` por `id_processo`** — o Holmes
|
||||
reentrega webhook e sem isso cada reentrega duplica linha.
|
||||
|
||||
## Resíduo do papel antigo
|
||||
|
||||
Este repo era a API que roda na VPS. Sobrou código que o conector **não usa**:
|
||||
|
||||
- `app/services/holmes.py` — o conector não fala com o Holmes
|
||||
- `app/v1/holmes/` — **pasta vazia**; os `.py` já foram apagados, o git ainda
|
||||
registra as remoções como pendentes
|
||||
- `app/services/controle_api.py` — telemetria no Oracle; só volta a fazer sentido
|
||||
na fase 4
|
||||
- `app/security.py` — JWT + auth via Oracle. **Não é usado**; a autenticação do
|
||||
conector é o `app/seguranca.py` (token + IP). Continua com os defeitos antigos:
|
||||
importa `db_instance` (inexistente) e usa `settings.api.jwt_secret` (que não
|
||||
existe no `Settings` novo).
|
||||
|
||||
Nada disso é importado no boot, então não quebra — mas é peso morto a limpar.
|
||||
|
||||
## Segurança
|
||||
|
||||
- **`ips_permitidos` está vazio** no `configs.json` atual (desligado, pra teste
|
||||
local). **Preencher com `179.197.230.154` antes de produção.**
|
||||
- **O par de chaves é de homologação.** Gerar um definitivo e trocar nos dois
|
||||
lados juntos.
|
||||
- **Sem TLS ainda** — depende de como o conector for publicado. A VPS manda CNPJ,
|
||||
notas e vencimentos; o envelope protege o conteúdo, mas o token viaja no header.
|
||||
- **Sem rate limiting.**
|
||||
- `/docs`, `/redoc` e `/openapi.json` ficam expostos quando `ambiente != prod`
|
||||
(atrás de basic auth). Fechar com `ambiente = prod` se não precisar.
|
||||
- Se entrar proxy na frente, o IP de origem vira o do proxy — a allowlist para de
|
||||
funcionar. Aí o uvicorn precisa de `--proxy-headers` e o `app/seguranca.py`
|
||||
passa a ler `X-Forwarded-For`.
|
||||
|
||||
## Middleware
|
||||
|
||||
- `block_scanners` é **denylist + heurística**, não allowlist estrita: qualquer
|
||||
path fora da blocklist com User-Agent normal **passa** e vira 404 na app.
|
||||
Não vaza nada, mas é mais permissivo do que parece.
|
||||
|
||||
## Empacotamento
|
||||
|
||||
- `pyproject.toml` aponta `readme = "README.md"` — o arquivo existe, mas confira
|
||||
se `pip install .` funciona; o Docker usa `requirements.txt` justamente pra
|
||||
não depender disso.
|
||||
- `PyJWT` está nas dependências mas só era usado pelo `app/security.py`, que
|
||||
saiu de circulação.
|
||||
Loading…
Add table
Add a link
Reference in a new issue