Skip to content

fix(catalogo): nenhum host padrao morto, override por env em todo servidor, check semanal de DNS/TLS - #230

Merged
fabianocruz merged 1 commit into
mainfrom
fix/catalog-dead-hosts
Sep 27, 2026
Merged

fabianocruz merged 1 commit into
mainfrom
fix/catalog-dead-hosts

Conversation

@fabianocruz

Copy link
Copy Markdown
Member

Closes #222
Refs #223 (nao fecha: 5 hosts de sandbox continuam mortos, ver "O que fica aberto")

Decisao do Fabiano em 26/09/2026 (memo de decisoes ALTA, itens 15, 16 e 17): opcao A em
catalog-satellites#2, #3 e #4. Uma PR so, porque os tres mexem no catalogo, no
README raiz e no mesmo job de CI novo. Nada foi publicado e nenhum npm deprecate foi rodado:
os comandos estao prontos no fim desta descricao.


Medicao (27/09/2026, antes de mexer)

dig +short <host> @8.8.8.8, dig +short <host> @1.1.1.1 e
curl -sS -m 10 -o /dev/null -w '%{http_code}' https://<host>/, rodados de um Mac em Sao Paulo.

host @8.8.8.8 @1.1.1.1 curl o que muda nesta PR
api.x402.org vazio vazio exit 6, nao resolve x402 obsoleto
ap2.googleapis.com 172.217.113.4 172.217.112.4 404, pagina generica do Google ap2 obsoleto
sandbox.ap2.googleapis.com 172.217.113.4 172.217.112.4 exit 60, certificado de outro nome ap2 obsoleto
commerce.googleapis.com 172.217.116.4 172.217.114.4 404, pagina generica do Google ucp obsoleto
sandbox.commerce.googleapis.com 172.217.118.4 172.217.117.4 exit 60, certificado de outro nome ucp obsoleto
api-sec.celcoin.com.br vazio vazio exit 6 sai do padrao da Celcoin
api.openfinance.celcoin.com.br 20.226.182.169 40.64.90.125 404 novo padrao de producao da Celcoin
sandbox.openfinance.celcoin.dev 4.228.155.179 4.228.155.179 404 sandbox da Celcoin, sem mudanca
login.openbank.stone.com.br vazio vazio exit 6 sai do token da Stone
accounts.openbank.stone.com.br 172.64.145.2 104.18.42.254 200 novo token da Stone
api.openbank.stone.com.br 172.64.145.2 104.18.42.254 404 API da Stone, sem mudanca
baas.c6bank.com.br, baas-sandbox.c6bank.com.br vazio vazio exit 6 c6 obsoleto
api.dock.tech, sandbox.api.dock.tech vazio vazio exit 6 dock obsoleto
api.matera.com vazio vazio exit 6 matera obsoleto
collection-prod.inspcdn.net vazio vazio exit 6 legiti obsoleto
api.caf.io vazio vazio exit 6 caf obsoleto
api.certta.com.br vazio vazio exit 6 certta obsoleto
api.unico.co, auth.unico.co vazio vazio exit 6 unico obsoleto
api.nubank.com.br vazio vazio exit 6 nubank obsoleto
api.sandbox.bb.com.br 170.66.196.28 170.66.14.91 exit 28, timeout sai do sandbox do BB
oauth.sandbox.bb.com.br 170.66.14.91 170.66.14.91 exit 60, certificado expirado sai do sandbox do BB
api.hm.bb.com.br 201.33.148.204 201.33.148.204 404 novo sandbox do BB
oauth.hm.bb.com.br 104.16.247.232 104.16.246.232 404 novo token de sandbox do BB
api-dev.pomelo.la, auth-dev.pomelo.la vazio vazio exit 6 saem do sandbox da Pomelo
api-stage.pomelo.la 104.18.8.54 104.18.9.54 200 novo sandbox da Pomelo
sandbox.api.btgpactual.com vazio vazio exit 6 fica, lista de mortos conhecidos
apihom.caixa.gov.br vazio vazio exit 6 fica, lista de mortos conhecidos
sandbox.api.itau.com.br vazio vazio exit 6 fica, lista de mortos conhecidos
apihom-bradescorip.bradesco.com.br vazio vazio exit 6 fica, lista de mortos conhecidos
sandbox-api.izipay.pe vazio vazio exit 6 fica, lista de mortos conhecidos

A lista dos 8 do memo se manteve: os mesmos 8 continuam sem host (c6, dock, matera, legiti, caf,
certta, unico, nubank), e a Stone continua morrendo no token. Varrendo o catalogo inteiro com o
job novo, apareceram mais dois sandboxes mortos que a ficha nao listava: o do BB (timeout e
certificado expirado) e o da Pomelo, alem dos cinco que a ficha ja citava.

Sobre os 404 do Google: 404 generico sozinho nao prova que o nome nao tem servico (a
translate.googleapis.com/v1 responde a mesma pagina). O que sustenta "sem endpoint" para
AP2/UCP e que todo caminho chamado pelos servidores falha, e que AP2 e UCP sao especificacoes,
nao APIs hospedadas pelo Google.

O que mudou

Consertos de host (fonte citada, host medido)

  • Celcoin (packages/payments/celcoin/src/index.ts): o padrao de producao troca
    api-sec.celcoin.com.br por https://api.openfinance.celcoin.com.br. A fonte e a doc da
    Celcoin (obtendo acesso as APIs):
    "Transactions e Baas: https://api.openfinance.celcoin.com.br/". Limite: a mesma pagina
    diz que producao exige mTLS com certificado emitido pela Celcoin e IPs cadastrados antes.
    Este servidor nao apresenta certificado de cliente. Chamado direto, POST /v5/token sem
    credencial responde 401 "O seu IP ou certificado digital nao foi reconhecido" (o sandbox
    responde 400 "Client_id is required"). Entao o conserto troca um NXDOMAIN por um host que
    existe e responde como Celcoin. Para producao funcionar de ponta a ponta, ainda precisa de um
    proxy com o certificado, apontado por CELCOIN_BASE_URL. O README e o docstring dizem isso.
  • Stone (packages/payments/stone/src/index.ts): o token sai de login.openbank.stone.com.br
    e vai para
    https://accounts.openbank.stone.com.br/auth/realms/stone_bank/protocol/openid-connect/token,
    com override por STONE_AUTH_URL. A fonte e
    docs.openbank.stone.com.br/docs/guias/token-de-acesso,
    que traz os seis enderecos (producao e sandbox). O token_endpoint do documento de descoberta
    OIDC do realm (/auth/realms/stone_bank/.well-known/openid-configuration, HTTP 200) confirma o
    mesmo endereco. O sandbox (sandbox-accounts... e sandbox-api...) ficou documentado no
    README como valor de override.
  • Banco do Brasil (sandbox, que e o padrao do BB_ENV): api.hm.bb.com.br e
    https://oauth.hm.bb.com.br/oauth/token. As fontes sao o guia client-credentials em
    apoio.developers.bb.com.br ("oauth.hm.bb.com.br (testes)"), a doc da API Cobranca ("Teste |
    https://api.hm.bb.com.br/cobrancas/v2") e o token_endpoint da descoberta OIDC. Producao
    continua como estava.
  • Pomelo (sandbox, que e o padrao do POMELO_ENV): api-stage.pomelo.la, com token em
    {host da API}/oauth/token. A fonte e developers.pomelo.la ("Stage: https://api-stage.pomelo.la /
    Produccion: https://api.pomelo.la", e curl -X POST "https://api.pomelo.la/oauth/token"). O
    audience continua o mesmo: e um valor de claim JWT, nao um host. A doc usa
    "audience": "https://auth-dev.pomelo.la". Essa linha leva o marcador
    catalog-hosts: not-a-host.

Obsoletos (sem endpoint vivo)

x402, ap2, ucp (itens 15 e 16) e c6, dock, matera, legiti, caf, certta,
unico, nubank (item 17). Em cada pacote:

  • o README do pacote, que e o que o npm mostra, ganha no topo a ressalva
    "Deprecated: no live endpoint", com o host medido e a variavel de override;
  • a description do package.json passa a comecar com DEPRECATED: no live endpoint (...), e a
    do server.json tambem (ate 100 caracteres, que e o limite do registry);
  • o docstring do src/index.ts ganha a mesma nota;
  • a versao sobe um patch ou prerelease, para a ressalva chegar ao npm antes do npm deprecate.

A ressalva velha da #225 ("No live endpoint. Checked on 2026-08-27") foi substituida no ap2 e no
ucp. Onde a pesquisa achou um host documentado pelo provedor, o README diz qual e e deixa
explicito que o servidor nao foi escrito contra ele: C6 (baas-api.c6bank.info, mTLS), Unico
(api.id.unico.app e identity.acesso.io) e CAF/Certta (api.combateafraude.com/v1, que a
propria CAF desrecomenda, e api.us.prd.caf.io). No Nubank, a unica API publica e o NuPay, que o
@codespar/mcp-nupay ja cobre. Trocar so o host desses pacotes nao os faria funcionar, porque o
auth e os caminhos tambem diferem, e por isso eles ficam obsoletos como a decisao manda.

README raiz: x402, UCP e AP2 saem do quick start (npx ...) e da arvore de decisao ("Agent
needs to buy something"). A tabela de protocolos e as tabelas do catalogo marcam os 11 como
deprecated: no live endpoint. C6 e Matera saem da lista de pacotes alpha recomendados.
examples/x402-demo/README.md parou de dizer que o mcp-x402 faz o fluxo por baixo.

Override por variavel de ambiente em todo servidor

Todo servidor le o host de <PREFIX>_BASE_URL, e de <PREFIX>_<PAPEL>_URL quando tem um
segundo host (STONE_AUTH_URL, BB_AUTH_URL, CIELO_QUERY_URL, TWILIO_VERIFY_URL...). O
<PREFIX> e o mesmo das credenciais do servidor. Os nomes antigos *_API_BASE (pluggy,
iniciador, caf, certta, bigdatacorp) continuam valendo como alias. Sem a variavel, o comportamento
e identico ao de antes. A mudanca e mecanica (process.env.X || <default de antes>) em 112
arquivos src/index.ts, contando os consertos de host acima. O README raiz e o docs/CONTRIBUTING.md documentam a convencao.

Job de CI: .github/workflows/catalog-hosts.yml

  • Roda segunda-feira as 09:17 UTC, por workflow_dispatch, e em PR que toque packages/*/*/src/**,
    packages/*/*/package.json ou o proprio script.
  • scripts/check-catalog-hosts.py calcula o conjunto de URLs a partir da fonte: um lexer de
    TypeScript pega todo literal de string que comeca com https://, fora de comentario, inclusive o
    default dentro de ${process.env.X || "..."}. Nada e listado a mao. Para cada host, resolve o
    DNS e completa um handshake TLS que verifica o certificado para aquele nome.
    • DEAD (NXDOMAIN, ou certificado de outro nome, expirado etc.) falha o job.
    • UNREACHABLE (timeout, reset) vira warning, porque depende de onde o runner esta. Hoje
      caem aqui servicios1.afip.gov.ar (DH fraco), api.nuvemfiscal.com.br (timeout) e
      demo.stpmex.com:7024.
    • O relatorio imprime o denominador: 129 servidores, 230 literais, 214 hosts (192 ok, 19
      dead, 3 unreachable), 4 hosts montados em runtime que nao da para sondar (shopify, vtex,
      chargebee e o live do adyen), 2 literais marcados not-a-host.
  • Duas excecoes, e as duas se policiam:
    • pacote obsoleto (description comeca com DEPRECATED): host morto e esperado. Se um
      obsoleto fica sem nenhum host morto, o job falha com STALE-DEPRECATION.
    • scripts/catalog-hosts-known-dead.json: tupla (servidor, host, motivo) para host morto
      em pacote nao obsoleto. Se o host volta a viver, ou some da fonte, o job falha com
      STALE-KNOWN-DEAD.
  • Todo servidor com URL padrao precisa ler algum process.env.*_URL. Se nao le, o job falha com
    NO-OVERRIDE. Hoje sao 0 servidores nessa situacao.
  • Em execucao agendada que falha, o job abre ou comenta uma issue unica,
    "catalog-hosts: dead host in the catalog".

Autoteste (--self-test, primeiro passo do job). Planta uma arvore temporaria e exige cada
veredito pelo nome:

  1. Extrator: acha o default dentro do override e dentro do template, e ignora URL em comentario,
    em prosa e em example.com.
  2. Controle positivo primeiro: registry.npmjs.org da ok e a arvore so com host vivo passa. Se o
    controle falha, o teste aborta, porque sem rede nada abaixo e evidencia.
  3. Host plantado codespar-selftest-dead-host.invalid (RFC 6761, nunca resolve): o job falha e o
    nomeia, sem culpar o pacote vivo.
  4. wrong.host.badssl.com da DEAD por certificado de outro nome, com badssl.com (mesmo operador)
    como controle ok.
  5. O mesmo host morto num pacote DEPRECATED nao falha. Um DEPRECATED so com hosts vivos falha
    como stale.
  6. Entrada na lista de mortos conhecidos para host vivo falha como stale. Sem a entrada, o mesmo
    host morto falha.
  7. Literal marcado not-a-host e pulado e contado. Um URL fixo sem override falha, e so aquele
    pacote.
  8. Ponta a ponta pela CLI: sai com codigo 1 e o host plantado aparece no stdout.

Resultado local, Python 3.12.13 / OpenSSL 3.6.3: 19/19 pass, tres execucoes seguidas. Contra o
catalogo depois desta PR: exit 0, "no unexpected dead host". Contra a main antes desta PR: exit 1,
com 24 hosts DEAD, entre eles api-sec.celcoin.com.br, login.openbank.stone.com.br e
api.x402.org. Observacao: com o python3 do macOS (3.9 com LibreSSL 2.8.3), rinne e safrapay
caem em UNREACHABLE por versao de TLS. Por isso o job usa 3.12 e o README pede 3.10+.

Testes

  • npm run build --workspaces --if-present: ok. packages/fraud/* nao esta em workspaces no
    package.json raiz (e nao e desta PR), entao rodei tsc --noEmit nos 4 pacotes de fraud:
    ok antes e depois.
  • npx vitest run: 36 arquivos, 153 passed | 34 skipped. Na main eram 150 passed; os 3 novos
    estao abaixo.
    • celcoin: sem CELCOIN_SANDBOX, token e endpoint vao para api.openfinance.celcoin.com.br;
      CELCOIN_BASE_URL sobrepoe o host nos dois modos.
    • stone: o token vai para a URL exata de accounts.openbank.stone.com.br, e a chamada
      seguinte para api.openbank.stone.com.br; STONE_AUTH_URL sobrepoe o host.
    • Sensibilidade: com o host antigo de volta no src/index.ts (e so ele), 3 testes ficam
      vermelhos, nomeando celcoin e stone. Com o conserto, voltam a verde.
  • python3 scripts/audit-catalog.py: exit 0. package.json, server.json e
    package-lock.json estao em sincronia.

Versoes

pacote npm hoje nesta PR por que
@codespar/mcp-celcoin 0.2.3 0.2.4 host de producao
@codespar/mcp-stone 0.2.2 0.2.3 host do token
@codespar/mcp-banco-do-brasil 0.1.0-alpha.4 0.1.0-alpha.5 hosts de sandbox
@codespar/mcp-pomelo 0.1.0 0.1.1 hosts de sandbox
@codespar/mcp-x402 0.1.4 0.1.5 ressalva no README do npm
@codespar/mcp-ucp 0.1.4 0.1.5 idem
@codespar/mcp-ap2 0.2.0-alpha.3 0.2.0-alpha.4 idem
@codespar/mcp-c6 0.1.0-alpha.3 0.1.0-alpha.4 idem
@codespar/mcp-dock 0.2.0-alpha.3 0.2.0-alpha.4 idem
@codespar/mcp-matera 0.2.0-alpha.3 0.2.0-alpha.4 idem
@codespar/mcp-legiti 0.2.0-alpha.3 0.2.0-alpha.4 idem
@codespar/mcp-caf 0.1.2 0.1.3 idem
@codespar/mcp-certta 0.1.2 0.1.3 idem
@codespar/mcp-unico 0.2.0-alpha.3 0.2.0-alpha.4 idem
@codespar/mcp-nubank 0.2.0-alpha.3 0.2.0-alpha.4 idem

Os outros cerca de 100 pacotes que so ganharam o override por variavel de ambiente nao foram
versionados, seguindo o precedente da #208: sem a variavel o comportamento e o mesmo, e 100
republicacoes recriariam o pico de downloads de bot. A mudanca chega ao npm na proxima release
natural de cada um.

O que fica aberto (por isso #223 nao fecha)

Cinco hosts de sandbox continuam mortos em pacotes que nao estao obsoletos, porque o host de
producao existe. Eles estao em scripts/catalog-hosts-known-dead.json, cada um com o motivo. O
modo padrao de btg, caixa, itau e bradesco e sandbox, entao quem instala sem mexer no *_ENV cai
num NXDOMAIN.

pacote host morto o que o provedor documenta
btg sandbox.api.btgpactual.com api.sandbox.empresas.btgpactual.com, token em id.sandbox.btgpactual.com/oauth2/token (outro caminho)
caixa apihom.caixa.gov.br sandbox como caminho do host de producao, api.caixa.gov.br:8443/sandbox/..., login em logindes.caixa.gov.br
itau sandbox.api.itau.com.br nenhum host de sandbox em pagina do Itau
bradesco apihom-bradescorip.bradesco.com.br docs atras de login
izipay sandbox-api.izipay.pe sandbox-api-pw.izipay.pe, token em /security/v1/Token/Generate (outro caminho)

Em nenhum dos cinco a troca e so de host, e a decisao A nao cobre esses casos. Precisa de
decisao: consertar o auth e os caminhos contra a doc, mudar o padrao para production ou marcar
o sandbox como indisponivel no README.

Depois do merge (acao de quem tem o npm)

O npm de @codespar/* pertence a codespar-npm (fabiano@codespar.dev) e a dangazineu
(npm owner ls). A ordem importa: publicar antes de rodar o npm deprecate, porque o
deprecate com * so marca as versoes que ja existem.

  1. Actions -> Publish to npm (publish.yml) -> workflow_dispatch com
    package = unpublished. O modo publica so os pares nome@versao que ainda nao estao no npm, ou
    seja, os 15 da tabela acima. Conferir no passo "Verify published packages".
  2. Actions -> Publish to MCP Registry (publish-registry.yml) -> server = all.
  3. Com a conta codespar-npm (OTP por e-mail, entao num terminal interativo e fora de um
    diretorio com .npmrc que tenha ${NPM_TOKEN}, por exemplo cd /tmp):
cd /tmp
npm deprecate '@codespar/mcp-x402@*' 'No live endpoint: api.x402.org does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/crypto/x402'
npm deprecate '@codespar/mcp-ap2@*'  'No live endpoint: AP2 is a spec; ap2.googleapis.com serves no API. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/payments/ap2'
npm deprecate '@codespar/mcp-ucp@*'  'No live endpoint: UCP is a spec; commerce.googleapis.com serves no API. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/payments/ucp'
npm deprecate '@codespar/mcp-c6@*'     'No live endpoint: baas.c6bank.com.br does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/banking/c6'
npm deprecate '@codespar/mcp-dock@*'   'No live endpoint: api.dock.tech does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/banking/dock'
npm deprecate '@codespar/mcp-matera@*' 'No live endpoint: api.matera.com does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/banking/matera'
npm deprecate '@codespar/mcp-legiti@*' 'No live endpoint: collection-prod.inspcdn.net does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/fraud/legiti'
npm deprecate '@codespar/mcp-caf@*'    'No live endpoint: api.caf.io does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/identity/caf'
npm deprecate '@codespar/mcp-certta@*' 'No live endpoint: api.certta.com.br does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/identity/certta'
npm deprecate '@codespar/mcp-unico@*'  'No live endpoint: api.unico.co does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/identity/unico'
npm deprecate '@codespar/mcp-nubank@*' 'No live endpoint: api.nubank.com.br does not resolve. See https://github.com/codespar/mcp-dev-latam/tree/main/packages/payments/nubank'
  1. Conferir que o deprecate valeu, pelo que o registry serve:
    npm view @codespar/mcp-x402 deprecated (e o mesmo para os outros 10) tem que devolver a
    mensagem.

🤖 Generated with Claude Code

…kly host check

- celcoin: production default api-sec.celcoin.com.br (NXDOMAIN) ->
  api.openfinance.celcoin.com.br, the host Celcoin documents. 0.2.4.
- stone: token URL login.openbank.stone.com.br (NXDOMAIN) ->
  accounts.openbank.stone.com.br (docs + OIDC discovery), STONE_AUTH_URL. 0.2.3.
- banco-do-brasil: sandbox hosts -> api.hm.bb.com.br / oauth.hm.bb.com.br. 0.1.0-alpha.5.
- pomelo: sandbox hosts -> api-stage.pomelo.la, token on the API host. 0.1.1.
- Deprecated (no live endpoint): x402, ap2, ucp, c6, dock, matera, legiti,
  caf, certta, unico, nubank. README caveat at the top, package.json and
  server.json description start with DEPRECATED, patch/prerelease bump so the
  caveat reaches npm. Out of the root README quick start and decision tree.
- Every server reads its host from <PREFIX>_BASE_URL (and <PREFIX>_<ROLE>_URL
  for a second host); old *_API_BASE names still work.
- scripts/check-catalog-hosts.py + .github/workflows/catalog-hosts.yml: weekly
  and on PRs that touch a server, resolve and TLS-handshake every default URL
  computed from the source; fail on a dead host outside the two policed
  carve-outs (deprecated packages, scripts/catalog-hosts-known-dead.json).
  --self-test plants dead, wrong-cert and live hosts and asserts each verdict.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@fabianocruz
fabianocruz merged commit d0a519a into main Sep 27, 2026
4 checks passed
@rapguit
rapguit deleted the fix/catalog-dead-hosts branch November 13, 2026 15:05
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.

catalog-satellites#2: @codespar/mcp-x402 aponta para api.x402.org, host que NAO EXISTE (NXDOMAIN). Os 10 to...

1 participant