Brabo API (0.1.0)

One key in normal operation; two during an AUTH_JWT_SECRET rotation.

A nonexistent email, wrong password, and a locked account all return exactly the same 401 response — same body, same status.

Always 204, even for an unknown token — answering 401 here would be a token-validity oracle.

Success goes to WEB_ORIGIN/ already with the session cookies set; failure goes to WEB_ORIGIN/login?oauth_error=1, without detailing the reason.

The state goes signed by HMAC with its OWN purpose — never the git connection-to-project flow's (see ADR 0084).

The presented refresh is consumed. Re-presenting an already-rotated token revokes the WHOLE family and records a security event — even when the cause was a client double-submit.

Responds 202 for both a new address and an already-registered one — the response doesn't reveal whether the account exists. In the second case nothing is created and the address's owner gets a notice.

Responds 202 for both a known and an unknown address. It is also the path for whoever was imported from Keycloak and hasn't set a password yet.

Revokes ALL of the user's sessions. Does not issue tokens: whoever resets the password is sent to login, so that compromising the email doesn't equal taking over the account in a single step.

Declarative index of the flow gates (ADR 0054). The screen derives from here which steps exist and who judges each one, instead of repeating the list in code — which is how it used to go stale unnoticed.

A gate cycle stalled for more than 2 h is parked instead of restarted on its own (ADR 0207). This is the human gesture that resumes it.

Public because whoever arrives is the user's BROWSER coming from the provider, without an api session. It isn't unrestricted: the state is verified by HMAC and without a valid one the call is refused. Never responds with JSON — always redirects, because a raw error body in a browser navigation would be a terrible experience.

Foundation for the declared blame pending item (PHASE 26b) — the UI that annotates the editor line by line doesn't exist yet. truncated warns when the file went past the annotated-lines cap.

Foundation for the rich dropdown (PHASE 26b) — today the ref selector is a plain text field. ahead/behind are relative to the repository's DEFAULT branch; null when the provider can't compute it (an honest degradation, not an error). It is NOT listBranches (which the Gitflow bootstrap uses) — it is its own operation, because enriching costs an extra call to the provider PER BRANCH.

UTF-8, cut at the byte cap with truncated: true when it's exceeded. A path that escapes the project folder is refused with 400 by the central check in RN-095 — never with 404, which would invite probing.

Foundation for the navigable list (PHASE 26b) — today the diff is only reachable by a known id (e.g. coming from Approvals); this route resolves how to reach the id without having to know it by heart. truncated warns when the list went past the per-call cap.

A null patch distinguishes the case where the provider didn't deliver the text (binary, or a patch too large) from the case where the text came back empty. Collapsing the two would make the screen say a changed binary didn't change. The truncated field warns when the file list went past the cap.

Search is NOT a git contract operation: it is composed over the tree and the content, and so is the only read whose cost grows with the size of the repository. Three budgets cap it — directories walked, files opened, and matches returned — and truncated says it stopped. filesScanned shows the cost it incurred.

Not recursive, by contract design: the tab navigates on demand, and requesting the whole tree of a large repository is exactly the traffic amplifier this phase forbids. truncated warns when the level went past the entry cap.

Doesn't redirect: returns the URL for the client to decide when to send the browser. The state goes signed by HMAC, and that is what prevents the callback from being forged.

SYNCHRONOUS: the response only comes back after the whole bootstrap (permanent branches, protections, templates) has run — there is no worker and no queue behind this. It is IDEMPOTENT AND RESUMABLE, so calling it again after a failure resumes from the step that failed. Track progress and read the failure reason via GET /projects/:id/git/bootstrap.

Validates access with getRepo and produces a PLAN (dry-run) of what the bootstrap would do — missing branches, missing protections, files. NOTHING is executed on the repository: decide afterward via plan/approve or plan/skip. Re-adopting the same repository converges (regenerates the plan without duplicating a row).

Which step it is on, whether it failed and where, and how many attempts there were. The step-by-step detail comes from the bootstrap.step_* events of the dedicated session.

protect_branches fails on a private repository on the free plan, and the wizard warns about this BEFOREHAND. Without this exit the only button was "Try again", which always fails for the same reason — and provision_failed makes the dashboard redirect the project back to the provisioning page, leaving it unreachable forever. Only a failure in PROTECTING can be acknowledged: it is the last step and the only one whose failure leaves a usable repository. The product's merge lock (RN-006) doesn't depend on the provider's protection and keeps applying.

decision: null with a plan present is the state where NOTHING runs — waiting for approval or as-is adoption (RN-045).

Approval is all-or-nothing: approving loose steps would break the dev←main, qa←dev, rc←qa cascade. What runs is the plan RE-DERIVED at execution time — equal to or smaller than what was shown, never larger.

Records the decision and doesn't touch the repository. The plan stays stored as evidence of what was deliberately not applied, and the bootstrap cursor is NOT tampered with — no step ran.

Runs a select 1. Reveals only whether the database responds; no topology or version. Public because the caller is kubelet, which carries no token.

Does NOT touch the database, on purpose. If it did, a slow Postgres would restart ALL replicas at once and turn degradation into a total outage. The pod is pulled from the load balancer by /health.

Not JSON: it's text/plain in exposition format. Public out of necessity (the scraper carries no token) and restricted by NETWORK — the production Ingress blocks this path at the edge and the NetworkPolicy only allows the monitoring namespace.

GitHub Releases proxy — platform accepts only linux-x64, linux-arm64, darwin-arm64. No authentication: the binary is not a secret. The bytes are checked against the checksums.txt of the same Release before anything is answered (ADR 0149, RN-525); the route does NOT verify the manifest signature — that is integrity, not provenance, and whoever verifies the signature is install.sh.

For the one-line installer, which runs where no mail transport is configured: the generated .env carries no mail variable, MAIL_TRANSPORT falls to log, and normal registration waits on an e-mail that never arrives. The account is born verified because whoever runs the installer already proved something STRONGER than controlling a mailbox — they control the machine, the .env and the Docker daemon. Normal registration is untouched. Refuses with 409 when the installation has ANY user: the condition is about the installation, not about this e-mail, so a migration restore silences the step by the same test. The password is never generated here and never stored anywhere but as an argon2id hash; the personal workspace (RN-410) is born in the same transaction.

The registry DESCRIBES, it does not execute: no gate becomes enforced because of it, and changing a field here changes no behavior at all. Each gate says where the proof that it passed lives (evidencia), because not every proof is in the event log.

If a version with the SAME hash already exists for the same name, no new version is created — the existing one is returned (the idempotency hit does not change the HTTP status: always 201, for simplicity — the body is identical to what would have been created).

A specific version looks up by equality; omitted, it looks up the most recent active version. 404 if the template (or the requested version) does not exist.

For the one-line installer, right after it creates the first account: the local agent needs a credential, and the only one that existed was bound to a PROJECT — in an installation that has none yet. The pair is generated ON THE MACHINE and only the public half arrives here; write the returned id into the private JWK as kid (RN-475), which is the only link between the file on disk and the public half on the server. There is no userId in the body ON PURPOSE: the owner is the installation's SOLE user, resolved by the api, so holding the service token never means choosing whose credential to mint. Registering REPLACES: the owner's active machine keys are revoked in the same transaction, so a reinstalled machine works and a thousand machine keys cannot exist. Project keys (ADR 0118) are never touched.

Never fails because of one provider: each one answers for itself in the report, with the reason it was skipped and the origin of the failure when there was one. A provider that did not respond is SKIPPED, not marked unavailable.

The SAME epic → story → task tree as the Backlog tab, through the same use case (three reads per project, never N+1). It is with this that the PO sees an orphan epic and a story with no task instead of re-creating what already exists (RN-164).

Every artifact.business_rule from the project's sessions — not just the current session's, which was the ceiling of the PO's kickoff context — with the full description and which stories already cite each rule. uncoveredCount is the pending item: a rule no story covers (RN-164). A project with no rule at all responds 200 with an empty list: "no rule captured yet" is not an error.

Called only by the engine, when Engine.Actions.TerminalExecutor decided the command belongs inside the real container (execution_mode: container with a REGISTERED running row). Proxies to ContainerBrokerPort.exec (ADR 0130/0134) — the last of the broker's five operations to gain a real caller. sucesso: false in the response — never a thrown error — is the NORMAL shape for a refused or unreachable broker: the container may have died or been removed from outside between the registered running row and this call (RN-486, registered and observed never merge), and that is a command failure, not a transport error.

Project identity, execution mode and the Architect's current image decision. The broker revalidates all of it before handing anything to the daemon — reading from here is not the same as trusting it, and the refusal names the field. No ABSOLUTE path is returned: the bind source is resolved by the daemon against the HOST filesystem, and a path from inside the api container would silently mount an empty folder. What travels is localizacao (RN-503) — which of the two broker roots to use, plus the relative segment that root does not cover.

Returns the clean origin (no credential embedded) and, for a remote provider, the workspace OWNER's token (RN-058) decrypted on the fly. Whoever consumes it injects the token per invocation and NEVER writes it to a file — .git/config sits inside the folder where RN-075 grants the dev agent auto-approved read access.