Brabo API (0.1.0)

Uma chave em operação normal; duas durante uma rotação de AUTH_JWT_SECRET.

E-mail inexistente, senha errada e conta bloqueada devolvem exatamente a mesma resposta 401 — mesmo corpo, mesmo status.

Sempre 204, mesmo para token desconhecido — responder 401 aqui seria um oráculo de validade de token.

Sucesso vai para WEB_ORIGIN/ já com os cookies da sessão gravados; falha vai para WEB_ORIGIN/login?oauth_error=1, sem detalhar o motivo.

O state vai assinado por HMAC com propósito PRÓPRIO — nunca o do fluxo de conexão de git ao projeto (ver ADR 0084).

O refresh apresentado é consumido. Reapresentar um token já rotacionado revoga a família INTEIRA e grava um evento de segurança — mesmo quando a causa foi um duplo envio do cliente.

Responde 202 tanto para endereço novo quanto para um já cadastrado — a resposta não revela se a conta existe. No segundo caso nada é criado e o dono do endereço recebe um aviso.

Responde 202 tanto para endereço conhecido quanto desconhecido. É também o caminho de quem foi importado do Keycloak e ainda não definiu senha.

Revoga TODAS as sessões do usuário. Não emite tokens: quem redefine a senha é mandado ao login, para que comprometer o e-mail não equivalha a tomar a conta num passo só.

Índice declarativo dos gates do fluxo (ADR 0054). A tela deriva daqui quais etapas existem e quem julga cada uma, em vez de repetir a lista no código — que era como ela envelhecia sem ninguém notar.

Ciclo de gate parado há mais de 2 h é estacionado em vez de reiniciado sozinho (ADR 0207). Este é o gesto humano que o retoma.

Pública porque quem chega é o NAVEGADOR do usuário vindo do provider, sem sessão da api. Não é irrestrita: o state é verificado por HMAC e sem um válido a chamada é recusada. Nunca responde JSON — sempre redireciona, porque um corpo de erro cru numa navegação do navegador seria uma experiência péssima.

Base para a pendência declarada do blame (FASE 26b) — a interface que anota o editor linha a linha ainda não existe. truncated avisa quando o arquivo passou do teto de linhas anotadas.

Base para o dropdown rico (FASE 26b) — hoje o seletor de ref é um campo de texto simples. ahead/behind são relativos à branch PADRÃO do repositório; null quando o provider não consegue calcular (degradação honesta, não erro). NÃO é listBranches (que o bootstrap do Gitflow usa) — é operação própria, porque enriquecer custa uma chamada a mais ao provider POR BRANCH.

UTF-8, cortado no teto de bytes com truncated: true quando passa dele. Caminho que escapa da pasta do projeto é recusado com 400 pela checagem central da RN-095 — nunca com 404, que convidaria a sondar.

Base para a lista navegável (FASE 26b) — hoje o diff só é alcançável por um id conhecido (ex.: vindo de Aprovações); esta rota resolve como chegar ao id sem ter de sabê-lo de cor. truncated avisa quando a lista passou do teto por chamada.

patch nulo distingue o caso em que o provider não entregou o texto (binário, ou patch grande demais) do caso em que o texto voltou vazio. Juntar os dois faria a tela dizer que um binário alterado não mudou. O campo truncated avisa quando a lista de arquivos passou do teto.

A busca NÃO é operação do contrato de git: é composta sobre a árvore e o conteúdo, e por isso é a única leitura cujo custo cresce com o tamanho do repositório. Três orçamentos a limitam — diretórios percorridos, arquivos abertos e acertos devolvidos — e truncated diz que ela parou. filesScanned mostra o custo que ela teve.

Não recursiva, por desenho do contrato: a aba navega sob demanda, e pedir a árvore inteira de um repositório grande é exatamente o amplificador de tráfego que esta fase proíbe. truncated avisa quando o nível passou do teto de entradas.

Não redireciona: devolve a URL para o cliente decidir quando mandar o navegador. O state vai assinado por HMAC, e é isso que impede o callback de ser forjado.

SÍNCRONA: a resposta só volta depois que o bootstrap inteiro (branches permanentes, proteções, templates) rodou — não há worker nem fila por trás. É IDEMPOTENTE E RETOMÁVEL, então chamá-la de novo depois de uma falha retoma do passo que falhou. Acompanhe o progresso e leia o motivo da falha por GET /projects/:id/git/bootstrap.

Valida o acesso com getRepo e produz um PLANO (dry-run) do que o bootstrap faria — branches faltando, proteções faltando, arquivos. NADA é executado no repositório: decida depois por plan/approve ou plan/skip. Readotar o mesmo repositório converge (regenera o plano sem duplicar linha).

Em que passo está, se falhou e onde, e quantas tentativas houve. O detalhe passo a passo vem dos eventos bootstrap.step_* da sessão dedicada.

protect_branches falha em repositório privado no plano gratuito, e o assistente avisa disso ANTES. Sem esta saída o único botão era "Tentar de novo", que sempre falha pelo mesmo motivo — e provision_failed faz o painel redirecionar o projeto de volta para a página de provisionamento, deixando-o inalcançável para sempre. Só falha em PROTEGER pode ser reconhecida: é o último passo e o único cuja falha deixa um repositório utilizável. A trava de merge do produto (RN-006) não depende da proteção do provider e continua valendo.

decision: null com plano presente é o estado em que NADA roda — aguardando aprovação ou adoção como está (RN-045).

A aprovação é tudo ou nada: aprovar passos soltos quebraria a cascata dev←main, qa←dev, rc←qa. O que roda é o plano RE-DERIVADO na hora da execução — igual ou menor que o mostrado, nunca maior.

Grava a decisão e não toca o repositório. O plano fica guardado como evidência do que deliberadamente não foi aplicado, e o cursor do bootstrap NÃO é mexido — nenhum passo rodou.

Executa um select 1. Revela só se o banco responde; nem topologia nem versão. Pública porque quem chama é o kubelet, que não carrega token.

NÃO toca o banco, de propósito. Se tocasse, um Postgres lento reiniciaria TODAS as réplicas de uma vez e transformaria degradação em queda total. O pod sai do balanceador pelo /health.

Não é JSON: é text/plain no formato de exposição. Pública por necessidade (o scraper não carrega token) e restrita por REDE — o Ingress de produção bloqueia este caminho na borda e a NetworkPolicy só libera o namespace de monitoramento.

Proxy de GitHub Releases — platform aceita só linux-x64, linux-arm64, darwin-arm64. Sem autenticação: o binário não é segredo. Os bytes são conferidos contra o checksums.txt da mesma Release antes de qualquer coisa ser respondida (ADR 0149, RN-525); a rota NÃO verifica a assinatura do manifesto — isso é integridade, não procedência, e quem verifica assinatura é o install.sh.

Para o instalador de uma linha, que roda onde nenhum transporte de e-mail está configurado: o .env gerado não traz variável de e-mail, MAIL_TRANSPORT cai em log, e o cadastro normal espera um e-mail que nunca chega. A conta nasce verificada porque quem roda o instalador já provou algo MAIS FORTE que controlar uma caixa de e-mail — controla a máquina, o .env e o daemon do Docker. O cadastro normal não muda. Recusa com 409 quando a instalação tem QUALQUER usuário: a condição é sobre a instalação, não sobre este e-mail, então a restauração de uma migração silencia o passo pelo mesmo teste. A senha nunca é gerada aqui e nunca é guardada em lugar nenhum senão como hash argon2id; o workspace pessoal (RN-410) nasce na mesma transação.

O registro DESCREVE, não executa: nenhum gate passa a ser aplicado por causa dele, e mudar um campo aqui não muda comportamento nenhum. Cada gate diz onde mora a prova de que passou (evidencia), porque nem toda prova está no event log.

Se já existe uma versão com o MESMO hash para o mesmo name, nenhuma versão nova é criada — a existente é devolvida (o acerto de idempotência não muda o status HTTP: sempre 201, por simplicidade — o corpo é idêntico ao que teria sido criado).

Uma version específica busca por igualdade; omitida, busca a versão active mais recente. 404 se o template (ou a versão pedida) não existe.

Para o instalador de uma linha, logo depois de criar a primeira conta: o agente local precisa de uma credencial, e a única que existia era presa a um PROJETO — numa instalação que ainda não tem nenhum. O par é gerado NA MÁQUINA e só a metade pública chega aqui; grave o id devolvido na JWK privada como kid (RN-475), que é o único vínculo entre o arquivo em disco e a metade pública no servidor. Não há userId no corpo DE PROPÓSITO: o dono é o ÚNICO usuário da instalação, resolvido pela api, então ter o service token nunca significa escolher de quem é a credencial cunhada. Registrar SUBSTITUI: as chaves de máquina ativas do dono são revogadas na mesma transação, então uma máquina reinstalada funciona e mil chaves de máquina não podem existir. Chaves de projeto (ADR 0118) nunca são tocadas.

Nunca falha por causa de um provider: cada um responde por si no relatório, com o motivo de ter sido pulado e a origem da falha quando houve. Provider que não respondeu é PULADO, não marcado indisponível.

A MESMA árvore épico → história → tarefa da aba Backlog, pelo mesmo caso de uso (três leituras por projeto, nunca N+1). É com ela que o PO vê um épico órfão e uma história sem tarefa em vez de recriar o que já existe (RN-164).

Todo artifact.business_rule das sessões do projeto — não só o da sessão corrente, que era o teto do contexto de kickoff do PO — com a description inteira e quais histórias já citam cada regra. uncoveredCount é a pendência: regra que nenhuma história cobre (RN-164). Projeto sem regra nenhuma responde 200 com lista vazia: "nenhuma regra capturada ainda" não é erro.

Chamada só pelo engine, quando Engine.Actions.TerminalExecutor decidiu que o comando cabe dentro do container real (execution_mode: container com uma linha running REGISTRADA). Faz proxy para ContainerBrokerPort.exec (ADR 0130/0134) — a última das cinco operações do broker a ganhar chamador real. sucesso: false na resposta — nunca um erro lançado — é a forma NORMAL de broker que recusou ou é inalcançável: o container pode ter morrido ou sido removido por fora entre a linha running registrada e esta chamada (RN-486, registrado e observado nunca se fundem), e isso é falha do comando, não erro de transporte.

Identidade do projeto, modo de execução e a decisão de imagem vigente do Arquiteto. O broker revalida tudo antes de entregar qualquer coisa ao daemon — ler daqui não é o mesmo que confiar, e a recusa nomeia o campo. Nenhum caminho ABSOLUTO é devolvido: a origem do bind é resolvida pelo daemon contra o sistema de arquivos do HOST, e um caminho de dentro do container da api montaria em silêncio uma pasta vazia. O que viaja é localizacao (RN-503) — qual das duas raízes do broker usar, mais o segmento relativo que a raiz não cobre.

Devolve a origem limpa (sem credencial embutida) e, para provider remoto, o token do DONO do workspace (RN-058) decifrado na hora. Quem consome injeta o token por invocação e NUNCA o grava em arquivo — .git/config fica dentro da pasta onde a RN-075 concede ao dev agent leitura auto-aprovada.