Skip to content

Instalar a CLI ​

A CLI finnest prepara, implanta e opera o Finnest Power na conta de nuvem da instituição. Ela roda na estação do operador ou num pipeline de CI e usa as credenciais de nuvem da própria instituição.

Plataformas suportadas ​

SistemaSuporte
macOS (Apple Silicon e Intel)Completo
Linux glibc (amd64 e arm64)Completo
Windows com WSL2Completo (instale dentro do WSL)
Windows nativoInstala e executa; a atualização automática não está disponível
Linux musl (Alpine)Não suportado

Instalação ​

A CLI é instalada pelo instalador. Ele atende macOS (Apple Silicon e Intel) e Linux glibc (amd64 e arm64):

bash
curl --proto '=https' --proto-redir '=https' -fL --progress-bar https://get.finnest.com.br | sh

No Windows nativo (x86_64), rode o mesmo comando num shell POSIX, como o Git Bash.

O instalador:

  • baixa a versão estável mais recente da CLI e o pacote de runtime correspondente;
  • confere o SHA-256 e a assinatura cosign de cada arquivo antes de instalar e interrompe a instalação se algo não conferir;
  • instala em ~/.finnest/bin, sem sudo, e adiciona esse diretório ao PATH do shell.

Opções úteis: --install-dir <diretório> para instalar em outro lugar e --no-modify-path para não alterar o PATH. Abra um novo shell depois da instalação para o PATH valer.

Confira a instalação:

bash
finnest version

Atualização ​

bash
finnest update --check   # só verifica se há versão nova
finnest update --yes     # instala a versão nova

A atualização troca a CLI e o pacote de runtime juntos. A configuração só a bloqueia quando a seção [plane] de ~/.finnest/config.toml tem self_update = false, valor que o finnest init grava por padrão. Nesse caso, apague a linha ou rode de novo o instalador. No Windows nativo, a atualização automática não está disponível: rode de novo o instalador. A versão da plataforma implantada acompanha a versão da CLI; veja Atualização de versão.

Pré-requisitos na estação do operador ​

  • Credenciais de nuvem:
    • AWS: AWS CLI com perfil ou SSO ativo na conta de destino.
    • Azure: az login concluído na assinatura de destino. No WSL, use a Azure CLI para Linux.
  • Node.js 20 ou mais recente no PATH. Prefira uma versão LTS em suporte, como a 22 ou a 24.
  • Acesso às imagens: na AWS, a conta liberada pela Finnest no registro de distribuição (recomendado); na Azure, ou na AWS sem esse registro, o usuário e o token somente leitura fornecidos pela Finnest. Veja Acesso às imagens.
  • DNS: a plataforma cria a zona do domínio da instalação (Route 53 na AWS, Azure DNS na Azure). A zona pai precisa delegar os registros NS para ela. Se a zona pai estiver na Cloudflare, a CLI pode fazer a delegação automaticamente com um token em ~/.finnest/credentials/cloudflare-api-token.

Os detalhes de permissões por nuvem estão em Deploy na AWS ou Azure.

Primeiros passos ​

O vídeo mostra a versão instalada e o setup num projeto novo: ele cria o finnest.toml, fixa as ferramentas, confere a prontidão e indica o próximo passo.

  1. Prepare a estação e o alvo de deploy. O setup grava o finnest.toml e roda as verificações iniciais:

    bash
    finnest setup --cloud=aws --environment=sandbox --participant-role=transmitter

    Papéis possíveis: transmitter (transmissora), receiver (receptora) ou both (ambos).

  2. Informe o material regulado (certificados ICP-Brasil, chaves e segredos). Use o Configuration Workspace, que mostra o que falta para o seu papel:

    bash
    finnest config workspace open --goal=apply

    Ou grave item a item com finnest secrets write <item> --file <arquivo> --yes.

  3. Confira a prontidão:

    bash
    finnest config readiness --goal=apply
    finnest doctor --cloud=aws --environment=sandbox
  4. Faça o deploy. Veja o passo a passo em Deploy na AWS ou Azure.

Receptora e iniciadora Open Finance (OFB) ​

A receptora de dados e a iniciadora de Pix do Open Finance Brasil só funcionam depois que a instalação guarda o material regulado delas. Sem esse material, o deploy não as configura. O caminho completo de uma instalação só OFB está no Guia OFB da participante; esta seção resume o que a CLI faz.

  1. Ligue o OFB e declare o egress das transmissoras na seção [opin] do finnest.toml:

    toml
    [opin]
    ofb_enabled = true
    ofb_egress_fqdns = ["<host de autorização da transmissora>", "<host de APIs da transmissora>"]

    Com ofb_enabled = true, a política de egress FAPI (finnest-allow-fapi-egress) já libera o Diretório do ambiente: auth, data, keystore, matls-api, matls-auth e web sob sandbox.directory.openbankingbrasil.org.br no sandbox e sob directory.openbankingbrasil.org.br em produção. Os hosts de cada transmissora (servidor de autorização e APIs) vão em ofb_egress_fqdns, em minúsculas e sem repetição.

  2. Grave o material com finnest secrets write, sem interação: --file para um arquivo, --pair-file para a chave de um certificado e --stdin para um valor. O valor fica no armazenamento local da estação; o deploy o publica no cofre de segredos da nuvem.

    ItemConteúdo
    ofb-receiver-state-secretAssina o state do redirecionamento; ao menos 32 caracteres
    ofb-receiver-secret-key-base64Chave AES-256 que cifra os segredos das conexões; 32 bytes em base64
    ofb-directory-client-idO client_id do software da participante no Diretório
    ofb-software-statement-idO UUID do software statement (papéis DADOS e PAGTO)
    ofb-receiver-jwks-jsonJWKS público: uma chave sig/PS256 e uma enc/RSA-OAEP, com kid únicos
    ofb-receiver-jws-private-jwk-json, ofb-receiver-jwe-private-jwk-jsonAs chaves privadas de assinatura e de cifra que o JWKS publica
    ofb-receiver-client-cert-pem, ofb-receiver-client-key-pemO certificado de transporte ICP-Brasil (folha e ACs) e a chave, para o mTLS
    ofb-receiver-jwe-retired-jwks-jsonSó durante a troca da chave de cifra: as chaves privadas aposentadas
    ofb-receiver-client-retired-cert-pem, ofb-receiver-client-retired-key-pemSó durante a troca do certificado: o certificado substituído e a chave
    bash
    finnest secrets write ofb-receiver-state-secret --stdin --yes <<< '<segredo de 32 caracteres ou mais>'
    finnest secrets write ofb-receiver-secret-key-base64 --stdin --yes <<< '<32 bytes em base64>'
    finnest secrets write ofb-directory-client-id --stdin --yes <<< '<client_id do software>'
    finnest secrets write ofb-software-statement-id --stdin --yes <<< '<UUID do software statement>'
    finnest secrets write ofb-receiver-jwks-json --file ./jwks.json --yes
    finnest secrets write ofb-receiver-jws-private-jwk-json --file ./jws-priv.json --yes
    finnest secrets write ofb-receiver-jwe-private-jwk-json --file ./jwe-priv.json --yes
    finnest secrets write ofb-receiver-client-cert-pem --file ./brcac.crt --pair-file ./brcac.key --yes

    Os nove primeiros itens são tudo ou nada. Quem os torna obrigatórios é o material, não o ofb_enabled: gravado qualquer item ofb-receiver-*, ofb-directory-client-id ou ofb-software-statement-id, o finnest doctor e a verificação prévia do deploy exigem os demais e os validam. Não há client_id de transmissora para gravar: a receptora se registra sozinha em cada transmissora (DCR) a partir do software statement.

    A ofb-receiver-secret-key-base64 não pode ser trocada depois de gravada, porque não há como recifrar os segredos que ela protege; o secrets write recusa um valor diferente. Os itens aposentados só existem durante uma troca (veja Rotação de certificados): o deploy os entrega ao banking enquanto estiverem gravados.

  3. Confira e faça o deploy:

    bash
    finnest secrets list --scope regulatory
    finnest doctor
    finnest deploy --preview

    Com o material gravado, o deploy declara o ExternalSecret ofb-receiver-material, que só o banking monta. Ele continua declarado mesmo com ofb_enabled = false: o ExternalSecret é protegido, e removê-lo travaria o deploy num delete protegido. Com o OFB desligado, o banking não monta nada dele.

  4. Confira o egress depois do deploy. A lista liberada precisa ter os hosts do Diretório e cada host de ofb_egress_fqdns:

    bash
    kubectl get ciliumnetworkpolicy finnest-allow-fapi-egress -o yaml

Painel interativo ​

Rodar finnest sem argumentos num terminal abre o painel interativo (cockpit). Ele mostra a prontidão do alvo e reúne as ações de verificação, configuração, histórico de execuções, alvos, deploy e atualização. Nenhuma ação altera a nuvem sem a sua confirmação. Ao abrir, as verificações ao vivo ainda não rodaram; no vídeo, a paleta de comandos (ctrl+p) roda a prontidão e o cabeçalho passa a mostrar o resultado.

TeclaAção
↑ ↓Navegar
enterAbrir a ação
gConfiguration Workspace
sTrocar o alvo de deploy
ctrl+pPaleta de comandos
?Ajuda
qSair

Saída para automação ​

Todo comando aceita --json, que imprime um envelope versionado. A exceção é o finnest schema, que imprime o próprio documento de schema, sem envelope. Para acompanhar um deploy longo, use --output=ndjson, que emite um evento por linha e termina com o envelope final. O formato do envelope está publicado em schema do envelope 2.0.0.

Próximos passos ​

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br