Skip to content
bucker

Approvals: who decides, and how Bucker knows it was a person

When policy holds an action for a human, an approval request opens. This page is about the decision: where it is made, what proves the person was there, and what a rejection must say. The rules about who may decide (human-only, fix:approve, the sole-approver rule) are in agent governance; the rules about what is held are the approval policies in Settings.

The decision page

Every request has one page where it is decided:

/org/<orgSlug>/approvals/<requestId>

That address carries the organization slug and the request id and nothing else: no token, no personal data, no decision verb. It is the only decision link a notice, a Slack message, an e-mail, a push or an MCP decisionUrl ever carries, and it is a pointer to a place, never a credential.

  • It needs your own session. Opening it signed out is the ordinary sign-in redirect back to the same address. Nothing about the page is pre-authenticated, so a link pasted into a channel or handed to an agent cannot be used by whoever holds it.
  • It is resolved for the person who opened it. GET /orgs/:org/approval-requests/:id/decision-page returns the request, a digest of the plan, the plan as the requester wrote it, the delegation chain, the policy that held it, your own progress, what a vote will ask of you, and whether you can decide with the reason if you cannot.
  • An opener inside the delegation chain sees the rule, never a button. If you started the run, or you are the person an agent acts for, the page says that the initiator of a run cannot be its sole approver and names who has to decide it. The vote is refused again on the server; the page is the explanation, not the control.
  • Everything an agent wrote is text. The plan and the names are shown as plain text: no Markdown, no links, no images, bidirectional and invisible characters removed, at most 4,000 characters.
  • A request in another organization, or in a project you cannot read, is a 404, the same as one that does not exist.

The decision card

Every request that is held for a person carries a decision card, built by the server when the request is filed and stored on the request (payload.card, at most 2,000 tokens and 32 KB). It is the same document on every channel: the decision page, the inbox, the Slack message, the e-mail, a push, and an MCP client that draws cards or reads six plain lines.

Section What it says Does it change?
plan The change as before and after, the plan text, and the digest a vote is bound to Never. It is what the request was filed with
target The kind, the id and the version of the object the plan was made against Never
effect The blast radius (each unmeasured field named, never shown as zero), how to undo it, how long it lasts, and the signal that verifies it Never
spend, chain, policy The cost effect and incident spend so far, who asked and for whom, and why the request exists Never
context The issue, the trace, how many sessions, the flag and variant, and the release the request's keys join to Re-read on the decision page, and stamped with when

So a decision page opened tomorrow still shows the plan, the target version and the digest the request was filed with, even if the target has moved since; only context is fresh, and the page says when it was read. The inbox shows the copy taken when the request was filed.

Every value that came from outside Bucker (your telemetry, the requester's words, an id a caller chose) is listed in the card's untrustedFields and shown as text. Links and images are removed from those values and URL schemes are broken (https[://]host), so nothing in a card can be clicked or fetched; you can still read where a plan would send data. A join across organizations is never made: an issue, flag or alert rule from another organization named in a request is simply not found.

Per channel:

  • Slack shows the effect and the digest, never the context. A request that needs a security key (CRITICAL, or dual control) says needs step-up: open in Bucker and offers no button, whether or not the request has a card (a request whose card could not be built is still CRITICAL).
  • MCP Apps (ui://bucker/decision-card) draws the card read-only with one action, which opens the decision page. There is no Approve or Reject in the view and no in-band vote.
  • No cards (a client that cannot draw them) gets six lines: what is asked, what a yes does, who must decide, when it lapses, the decision page, and that nothing has been done yet.
  • approvals_list (MCP, read-only) lists your own pending and recent requests with their status, expiry and, for a rejected one, its reason code. queuePosition is always null until batching ships.
  • Webhooks send approval.requested and approval.decided with the request id, action, status and expiry only (see outbound webhooks).

The inbox lists requests and still decides the simple ones in place. A CRITICAL request is decided on the page only, approve and reject alike (the inbox links to it), because only the page can collect a security-key confirmation. A request that needs dual control is known to the server; an in-place vote on one is refused with the same link.

Step-up: proof that you are here, for this plan

A session says how you began a sitting, perhaps days ago. For a request that is worth more than a cookie, a vote needs a fresh confirmation tied to the decision itself.

When a vote needs one (approving or rejecting):

  • the request is CRITICAL, or
  • the request needs dual control, from either side: the policy that held it froze minApprovers of 2 or more, or its action is dual-control in the registry and the action's dualControlWhen condition holds (an unmeasured input counts as holding).

Each vote on such a request needs its own confirmation, not only the last. A rejection is included on purpose: on these requests one "no" ends the request, so a veto cast from a stolen session would deny the change the incident is waiting on.

What the confirmation is. Deciding asks your security key or passkey to sign a challenge that is sha256(requestId ‖ planDigest ‖ serverNonce):

Property Meaning
Bound to the request An answer made for one request is refused on another.
Bound to the plan The server recomputes the digest from the request at vote time. A plan that changed after the prompt was drawn no longer verifies.
Single use The challenge is spent by the first attempt, right or wrong.
Five minutes It expires. The page asks for a challenge at the moment of the vote, not at load.
Charged Every attempt counts against the account's MFA attempt budget, and a failure is a MFA_CHALLENGE_FAILED security event with path approval_vote.

The challenge comes from POST /orgs/:org/approval-requests/:id/step-up/challenge, or from the session step-up door POST /auth/mfa/webauthn/step-up/options with a body naming the request. It is a separate purpose from the session step-up, so a challenge minted for one can never be spent on the other.

TOTP is the narrow fallback. A six-digit code is accepted only when you have no registered key and your organization does not require a phishing-resistant factor. A code cannot be tied to the plan, so the receipt records which method was used.

What is recorded. ApprovalVote.stepUp holds { method, digest, at }: the method (security_key, passkey or totp), the plan digest the proof was bound to, and when. Never a secret, an assertion or the nonce. The vote's channel and the request's decisionChannel record where it was cast.

When it is not enough or not possible. A vote without a valid confirmation is a 403 with details.refusalCode: "STEP_UP_REQUIRED", a stepUp reason (missing, invalid, method_not_allowed) and a remedy naming the enrolment page and the decision page. The refusal is audited as approval.step_up.refused with the channel and session. On a request that needs no confirmation, one that is offered with a vote is still verified and recorded, and refused if it does not verify.

Channels that cannot carry a WebAuthn assertion cannot satisfy it, whatever they send: Slack, mobile push, chat and e-mail. A Slack Approve, or a rejection from Slack's reason menu, on a request that needs a confirmation records no vote and answers with the decision-page link. The same holds for the MCP surface: no tool decides.

Rejections that teach

A rejection needs two things:

  • a reasonCode from the closed list wrong_target, too_wide, not_needed, unsafe, evidence_insufficient, duplicate, stale, other, and
  • words (reasonText) of at least 10 characters saying what the next proposal should do differently.

Without either it is a 400 and the request stays open. The code lands on the request (reasonCode, with the words in reason) and in the metadata of the approval.reject audit row, beside the channel and the session. Codes are labels for whatever raised the request. Slack's reason menu files under the same list; a bare Slack Reject records nothing and points at the menu or the page.

Where the decision is audited

Row When Notes
approval.approve each approving vote channel, sessionId, stepUpRequired, stepUpMethod in the metadata
approval.reject a rejection reasonCode, channel, sessionId, stepUpRequired, stepUpMethod in the metadata
approval.step_up.refused a vote turned away for want of a valid confirmation why, channel, sessionId

sessionId is the identifier of the access token behind the vote: attribution, never the token.