feat!: migrar client e mock para o contrato oficial v1.1.0 (0.2.0)

[Mozurok]

Migra os dois pacotes do OpenAPI v0.0.10 para o v1.1.0, publicado pelo CGIBS em 24/08/2026, e entrega o guia de migração. Quebra compatibilidade com a linha 0.1.x.

A decisão que moldou o resto: quem assina

O contrato exige X-JWS-Signature nas 43 operações: JWS Compact Detached sobre o corpo canonicalizado em JCS, RS256, sete atributos no protected header.

O b64: false (RFC 7797) decide o desenho. Ele faz a assinatura cobrir os bytes crus do payload, então quem assina precisa ver exatamente o que vai na rede. Se a assinatura viesse pronta de fora, o chamador serializaria por conta própria e as duas serializações divergiriam em ordem de chave, formato de número ou escaping — produzindo uma assinatura válida sobre bytes que ninguém enviou, e um 4xx sem pista.

Então o client faz a parte difícil e delega só o RS256:

createSplitClient({
  baseUrl,
  kid: "minha-chave-01",
  assinar: (bytes) => hsm.signRS256(bytes),   // a chave privada é sua
})

Existe uma serialização só, e é a que vai na requisição.

O que mudou no contrato

	v0.0.10	v1.1.0
rotas	32	35
schemas	57	78
autenticação de mensagem	4 headers	X-JWS-Signature
stream	{idPsp}/tributos	{cnpjRaizPspRecDir}/transacoes
Mecanismo de Ocorrências	—	3 rotas

Os quatro headers obrigatórios não existem mais. Sumiram de components.parameters e o manual v1.1.0 não os cita uma única vez.

Campos renomeados: cnpjCpfPagOrig → cnpjPagOrig (que passou a aceitar só CNPJ, o pagador pessoa física saiu do contrato), valorTotalCbs/Ibs → vlTotalCbs/Ibs, fromNsu/toNsu → nsuInicial/nsuFinal, tributos → transacoes. Tipos: numIdentcBaixa e nsuId viraram string. Formatos fixos: numCodBarras com 44 dígitos, idLote = idInfSegr + sequencial (40 posições). dtHrDisp entrou como obrigatório no Super Inteligente. PATCH /api/v1/pix-automatico deixou de existir.

Três escolhas que valem revisão

1. O pós-processamento do MOC no codegen. MocOcorrenciaSol e Not usam allOf com not, e o openapi-typescript emite tipos inconstruíveis: o discriminador vira o literal com o nome do schema (arrj: "MocOcorrenciaSol" em vez de BOL|PXE|...) e o not vira Record<string, never>, zerando o resto. Pus a reescrita no gerador, não num override manual, para que ela suma sozinha quando o upstream corrigir. O teste moc-tipos.test.ts existe porque sem ele isso quebra em silêncio: nada mais no pacote toca aqueles schemas, então tsc sairia 0 com as duas rotas POST inutilizáveis.

2. O mock confere a forma da assinatura, sem exigir. Verificar de verdade obrigaria quem roda npx splitbr-mock a gerar par de chaves antes da primeira resposta, e o valor do mock é não precisar de setup. Aceitar qualquer string não ensinaria nada. Conferir a forma pega o erro provável em produção: JWS bem-formado com b64 errado, ou payload anexado em vez de detached. buildServer({ exigirAssinatura: true }) liga o modo fiel.

3. O MOC não ganhou matriz M/O/N-E. O princípio do repo é que as matrizes são o produto, mas aqui o próprio spec já codifica a regra por arranjo com oneOf, required e additionalProperties: false, e o Ajv já a aplica. Criar matriz duplicaria a fonte da verdade. Contrariei a convenção de propósito; se preferir a coerência, dá para reverter só isso.

Versão: 0.2.0, não 1.0.0

Pré-1.0, a quebra se sinaliza no minor, e ^0.1.1 não atravessa minor em 0.x — quem depende assim já fica protegido. Subir para 1.0.0 afirmaria uma estabilidade que o cenário não sustenta: três manuais da família não foram publicados, dois são minuta, o Manual de Segurança (que descreve o JWKS por trás da assinatura) não existe, e a plataforma pulou de 0.0.10 para 1.1.0 em dois meses.

Verificação

build       OK
typecheck   0 erros
testes      227  (71 client + 115 mock + 41 detector)   antes: 162
drift       4/4 MATCH
site        build OK, guia na navegação
tutorial    primeiro curl rodado contra o mock: 201, 1 item válido

O client saiu de 27 para 71 testes: vetores da RFC 8785 (incluindo o caso do emoji antes do hebraico, que separa ordenação por code unit de code point), verificação RS256 real com par de chaves gerado, teste de adulteração de byte, e a prova de tipo do MOC.

Guia de migração

Novo em docs/site/migracao.md, na navegação. Além do campo a campo, avisa dois erros que custam tempo: o do b64: false acima, e que nsuId virou string, então "9" > "10" é verdadeiro e comparar NSU com > passou a ordenar lexicograficamente.