Skip to content

fix(brasil-api): get_cnpj para de tomar 403 (User-Agent no cliente HTTP) - #226

Merged
fabianocruz merged 1 commit into
mainfrom
fix/catalogo-clientes-http
Aug 29, 2026
Merged

fabianocruz merged 1 commit into
mainfrom
fix/catalogo-clientes-http

Conversation

@fabianocruz

@fabianocruz fabianocruz commented Aug 28, 2026 •

Copy link
Copy Markdown
Member

Lane catalogo da auditoria. Dois achados atribuidos: catalog-satellites#5 (consertado aqui) e
catalog-satellites#10 (nao cabe neste repo, detalhado abaixo). catalog-satellites#11 ficou
fora da lane por despacho.


catalog-satellites#5 — get_cnpj devolve 403 em uso normal (CONSERTADO)

Mecanismo

packages/identity/brasil-api/src/index.ts:56 monta a unica requisicao HTTP do servidor:

const res = await fetch(`${BASE_URL}${path}`, {
  method: "GET",
  headers: { "Content-Type": "application/json" },
});

A ficha diz "o cliente HTTP nao manda User-Agent". Medi antes de mexer e a descricao precisa e
outra: o fetch do Node (undici) preenche o header sozinho quando o chamador nao passa nada.
Servidor HTTP local, Node v25.5.0, mesma chamada acima:

headers recebidos pelo servidor local: {
  "content-type": "application/json",
  "accept": "*/*",
  "user-agent": "node",
  ...
}

O que a BrasilAPI rejeita e esse node. Medido ao vivo em 28/08/2026, tres execucoes seguidas,
mesma URL, so o header mudando:

--- run 1 ---
UA=node                          cnpj: 403
UA=codespar-mcp-brasil-api/0.2.2 cnpj: 200
--- run 2 ---
UA=node                          cnpj: 403
UA=codespar-mcp-brasil-api/0.2.2 cnpj: 200
--- run 3 ---
UA=node                          cnpj: 403
UA=codespar-mcp-brasil-api/0.2.2 cnpj: 200

GET /cep/v1/01001000 responde 200 com UA=node, e por isso o problema so aparecia no CNPJ. Como
brasilApiRequest e o caminho unico das 24 tools, a correcao vale para todas.

Limite do que foi medido: as tres execucoes sairam de um unico host, no mesmo minuto, mudando so o
header. Isso estabelece que o discriminador e o User-Agent, nao que a regra da borda seja
identica para toda origem de rede. Nao testei de uma segunda rede.

O que mudou

  • packages/identity/brasil-api/src/index.ts: constante USER_AGENT = "codespar-mcp-dev-latam/mcp-brasil-api/0.2.2" e o header no fetch. O formato segue o que os
    servidores mais recentes do repo ja usam (packages/payments/malga/src/index.ts:65,
    packages/payments/rinne/src/index.ts:76). Verifiquei ao vivo que essa string tambem devolve 200.
  • packages/identity/brasil-api/src/__tests__/index.test.ts: dois testes de unidade.
  • packages/identity/brasil-api/src/__tests__/contract.test.ts (novo): teste de contrato ao vivo,
    gated por BRASIL_API_CONTRACT, seguindo test-utils/contract.ts. Nao usa credencial: a
    BrasilAPI e publica e o gate so serve para nao botar rede no CI.
  • packages/identity/brasil-api/tsconfig.json: "exclude": ["src/__tests__"]. Isso nao e
    cosmetico
    e esta explicado na secao "Efeito colateral" abaixo.
  • docs/CONTRIBUTING.md: como rodar o teste de contrato novo e o aviso do exclude.

Por que os testes nao caem nas armadilhas

O defeito depende do comportamento de um terceiro, entao ele nao foi escrito a mao: o vermelho vem
da API real. O teste de contrato tem controle positivo pareado dentro do mesmo it: dispara a
mesma URL duas vezes, uma com o UA default e outra com um UA descritivo, e exige que a segunda
passe antes de exigir que a primeira falhe. Se a BrasilAPI estiver fora do ar ou limitando este
host, o controle falha primeiro e a asserção de rejeicao nao e lida como sinal.

O teste de unidade tambem carrega controle positivo: le content-type do mesmo objeto capturado
antes de olhar o user-agent. Se o instrumento (new Headers(init.headers)) estivesse quebrado, o
content-type viria nulo e o teste acusaria a sonda, nao o codigo.

Vermelho antes

Unidade (npx vitest run packages/identity/brasil-api/src/__tests__/index.test.ts):

 × outbound HTTP identity > sends an identifying User-Agent on get_cnpj 4ms
   → no User-Agent on the outgoing request: undici will send 'node' and BrasilAPI answers 403 on /cnpj: expected null not to be null
 × outbound HTTP identity > sends it on every route, not only CNPJ 3ms
   → get_cep went out without a User-Agent: expected null not to be null

 Test Files  1 failed (1)
      Tests  2 failed | 11 passed (13)

Contrato ao vivo (BRASIL_API_CONTRACT=1 npx vitest run .../contract.test.ts), erro produzido pela
API de verdade, nao redigido por mim:

 FAIL  ... > mcp-brasil-api [contract] > get_cnpj resolves a real company against the live API
AssertionError: live get_cnpj failed: Error: BrasilAPI 403: {"error":{"code":"403","message":"Forbidden","id":"gru1::g5hjz-1787927309441-f15628ec4d35"}}
 ✓ mcp-brasil-api [contract] > control: the edge is what rejects the default Node User-Agent 91ms

 Test Files  1 failed (1)
      Tests  1 failed | 1 passed (2)

Verde depois

 ✓ packages/identity/brasil-api/src/__tests__/index.test.ts (13 tests) 85ms
 Test Files  1 passed (1)
      Tests  13 passed (13)

 ✓ packages/identity/brasil-api/src/__tests__/contract.test.ts (2 tests) 220ms
 Test Files  1 passed (1)
      Tests  2 passed (2)

Suite inteira do repo (npm test), antes e depois:

main limpo:  Test Files  36 passed | 2 skipped (38)   Tests  148 passed | 32 skipped (180)
este branch: Test Files  36 passed | 3 skipped (39)   Tests  150 passed | 34 skipped (184)

Delta: +2 testes de unidade passando, +2 de contrato pulados sem credencial. Nenhum teste existente
mudou de estado.

Revertido confere

Devolvi so src/index.ts para o estado de main (git checkout no arquivo de producao), mantendo
os dois arquivos de teste, e rodei de novo:

--- UNIT ---
 × outbound HTTP identity > sends an identifying User-Agent on get_cnpj
 × outbound HTTP identity > sends it on every route, not only CNPJ
      Tests  2 failed | 11 passed (13)
--- CONTRACT ao vivo ---
 × get_cnpj resolves a real company against the live API
   → live get_cnpj failed: Error: BrasilAPI 403: {"error":{"code":"403","message":"Forbidden","id":"gru1::hj8dv-1787927410988-575e07b694d9"}}
 ✓ control: the edge is what rejects the default Node User-Agent
      Tests  1 failed | 1 passed (2)

Os testes nao espelham a logica: com o arquivo de producao revertido eles falham, e o controle
positivo continua verde nos dois estados.

Divergencia da ficha proposta

A ficha sugeria, para "fechar a classe", mover o fetch para um helper em packages/shared
(@codespar/mcp-shared) e fazer os servidores usarem esse helper. Nao fiz, e recomendo nao
fazer assim.
Medida:

$ grep -rl "@codespar/mcp-shared" packages/*/*/package.json
(nenhum resultado: zero pacotes dependem dele)

$ npm view @codespar/mcp-shared version
npm error 404 Not Found - GET https://registry.npmjs.org/@codespar%2fmcp-shared - Not found

@codespar/mcp-brasil-api e publicado no npm e instalado via npx. Declarar dependencia de um
pacote que nao existe no registry quebraria a instalacao de todo mundo, para trocar um header
duplicado por um import. Adotar o helper e uma mudanca de empacotamento (publicar o
mcp-shared primeiro), nao parte deste conserto. Fica registrado como o que este PR nao fecha.

Efeito colateral que o exclude do tsconfig evita

test-utils/contract.ts fica fora do rootDir de qualquer pacote. Sem
"exclude": ["src/__tests__"], o tsc do pacote nao so falha:

src/__tests__/contract.test.ts(6,8): error TS6059: File '.../test-utils/contract.ts' is not under
rootDir '.../packages/identity/brasil-api/src'.

como ainda emite um test-utils/contract.js em CommonJS ao lado do .ts. Bati nisso durante o
trabalho: com esse arquivo no disco, os 4 arquivos de contrato do repo passam a falhar em bloco com
Vitest cannot be imported in a CommonJS module using require(). Os dois pacotes que ja tem teste
de contrato (payments/mercado-pago, payments/celcoin) ja carregam esse exclude; brasil-api
agora tambem. Efeito bonus: dist/ deixa de embarcar os testes no pacote publicado (antes:
dist/index.js, dist/index.d.ts, dist/__tests__/...; agora so os dois primeiros).

O que este PR nao fecha

  • Nao mexe nos outros ~130 servidores. A ficha recontou que so 8 setam User-Agent; a classe
    continua aberta. Este PR conserta o unico caso medido como alcancavel e quebrado em producao
    (get_cnpj = 403 em toda chamada). Varrer o resto exige medir provedor por provedor, e o
    caminho Celcoin esta congelado ate a homologacao de 31/08.
  • Nao publica @codespar/mcp-shared nem centraliza o cliente HTTP (motivo acima).
  • Nao corrige a divergencia de versao dentro do brasil-api (package.json e server.json dizem
    0.2.2, o new Server(...) em index.ts ainda diz 0.2.1, em duas ocorrencias). Fora do
    escopo da ficha e sem medicao de impacto; deixei intacto de proposito.

catalog-satellites#10 — os dois repos satelite nao tem CI (NAO CONSERTADO AQUI)

Confirmei o achado, mas ele nao pode ser feito neste PR: o patch pede workflows em
codespar/x402-monetization-examples e codespar/agentic-payments-standards, e a lane tem clone
so de mcp-dev-latam. Abrir PR nos outros dois seria trabalhar fora do clone da lane.

Verificacao que fiz (leitura pura, via API):

$ gh api repos/codespar/x402-monetization-examples/contents/.github
{"message":"Not Found","status":"404"}

$ gh api repos/codespar/agentic-payments-standards/contents/.github
{"message":"Not Found","status":"404"}

Os dois sao publicos, default_branch: main, e nao tem diretorio .github nenhum. O achado
procede. Controle positivo do mecanismo: este repo tem CI de verdade
(.github/workflows/ci.yml, jobs build-and-test, catalog, security), e foi contra ele que
rodei a verificacao de estado do CI abaixo.

Uma ressalva sobre o teste proposto na ficha ("PR de controle com import quebrado"): esse teste so
existe depois que o workflow esta no repo de destino, e o vermelho dele e "o PR nao tem check
nenhum", que nao da para rodar localmente. Quem pegar o achado precisa de clone dos dois repos e
de dois PRs separados.

Estado real do CI

Reproduzi os tres jobs do .github/workflows/ci.yml localmente neste branch:

  • build-and-test: npm run build --workspaces --if-present -> exit 0, zero error TS;
    npm test -> 36 arquivos passando, 3 pulados, 150 testes passando, 34 pulados.
  • catalog: npm run audit:catalog -> exit 0 (so achados MED preexistentes, sobre headers
    ## Authentication faltando em tres servers da Colombia; nenhum HIGH).
  • security: o grep de segredo do workflow -> No hardcoded secrets found.

E o CI do GitHub Actions rodou neste branch e voltou verde nos tres jobs
(run 33180857042):

build-and-test  pass  2m33s
catalog         pass  5s
security        pass  16s

Nenhum job vermelho, nenhum check pendente. O teste de contrato novo aparece como pulado no CI,
que e o comportamento pretendido: sem BRASIL_API_CONTRACT ele nao toca a rede.

Segredo

Nenhum. O CNPJ usado no teste de contrato e 00000000000191 (Banco do Brasil S.A.), registro
publico. A BrasilAPI nao tem autenticacao, e nenhum .env foi criado ou lido.

Node's fetch (undici) fills in "User-Agent: node" when the caller omits the
header. BrasilAPI's edge answers 403 Forbidden to that UA on /cnpj, so
get_cnpj failed for every user of this server, on every call, not just in
some error path. Measured live on 2026-08-28 against brasilapi.com.br:

  GET /cnpj/v1/00000000000191  UA "node"                        -> 403
  GET /cnpj/v1/00000000000191  UA "codespar-mcp-dev-latam/..."  -> 200
  GET /cep/v1/01001000         UA "node"                        -> 200

brasilApiRequest now sets the same UA format the other servers in this repo
use (payments/malga, payments/rinne).

Tests: two unit tests pin the header on the request the server builds, and a
new contract.test.ts produces the third-party half for real (gated by
BRASIL_API_CONTRACT, skipped in CI) with a paired positive control that shows
the gate is BrasilAPI's, not a dead probe.

The tsconfig exclude is required, not cosmetic: test-utils/contract.ts lives
outside the package rootDir, so without it tsc fails and still emits a
CommonJS test-utils/contract.js that breaks every contract test in the repo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@fabianocruz
fabianocruz merged commit 65c66c0 into main Aug 29, 2026
3 checks passed
@fabianocruz
fabianocruz deleted the fix/catalogo-clientes-http branch August 29, 2026 02:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant