Files
stack/agents/gander/work/queue-252/DESIGN.md
T

16 KiB

Row 252: Console inbox Approve and Deny

Revision 1, 2026-10-21. Gander. Reviewer Webby. Gate owner Sage. Vikunja #435 (J2), Gitea #1753. Design only, not approved for implementation. Brief: 640aa03f2:docs/plans/2026-10-21_console-inbox-approve.md. Design base: row 196 rebased build 64539c96b on a36523713. Row 196 verification and Duckworth's manifest review remain pending. Row 252 code must wait for Webby approval, the row 196 landing, and the PRD amendment described below.

1. Decisions that get buttons

The first cut covers grant requests only. Q188 and #435 ask for that case; turning every decision into a Console write would widen this security slice. Other decisions keep today's option text and copyable mosaic decide ID KEY.

Eligibility is determined by the bus from the original authoritative raise:

  • The decision belongs to the selected business, is open and routed to human.
  • Its action is credential.mint and the broker's original decision.raise event has a validated grant binding. A question or option containing the word grant, an action supplied by the browser, or a copied authorization object does not qualify.
  • There are exactly two distinct current option keys. The broker's recorded approvalChoice names one. Approve uses that key; Deny uses the other key. Both controls display the real option text. No guessed yes or no key.
  • Missing binding, ambiguous options, a superseded/closed decision, a technical or role-routed decision, and non-grant authorization requests get no buttons. Existing terminal handling remains available where it is available today.

The bus adds a read-only console-resolution description to the decision view: eligibility, the exact two keys and labels, a safe grant summary, and a digest of decision id, business, options, approvalChoice and original grant binding. It contains no token or key material. This description helps the UI; the final write recomputes every check from authoritative state in its transaction. Approving records consent and starts the existing grant workflow. It does not claim the external enrollment or credential operation has already succeeded. Deny resolves with the non-approval key and starts no grant executor.

2. Identity and the one bus verifier

The resolving identity is (provider id, issuer, sub) from the request's live row 192 OIDC session. Session.name is display text, never authority. Headers, POST fields and a shared secret cannot select the human. ID or access tokens, session cookies and client secrets never become bus credentials or audit text.

Extend row 196 verifyPrincipal rather than create a second verifier. Add a Console-owner variant of its human proof with a reviewed same-tree console-cli.mjs path and a separate MOSAIC_BUS_CONSOLE_NONCE namespace. It must:

  1. Match the accepted Unix connection's SO_PEERCRED pid and instance uid.
  2. Verify the fixed Console wrapper path and initial spawn nonce, using the existing human walk and all marker, agent binary and launch-record refusals.
  3. Require the exact same-tree webui cli.mjs serve as direct parent, and reread child/parent identity as row 196 does for Console users. No CLI respawn.
  4. Bind business and the provider/issuer/sub tuple to initial per-spawn metadata. The Console constructs these only from the session verified for this request. The wrapper refuses body overrides. The bus compares proof metadata to that initial environment and to trusted current console.sso owner subjects.
  5. Resolve to businesses[business].human only when the tuple is an allowed owner subject in this instance's checked console.sso configuration. Unknown subjects, changed mapping, missing/invalid configuration and user principals refuse. A terminal owner still works if Console configuration is unavailable.

The runtime receives the checked owner-subject map through its trusted startup API, never through a socket verb. Provider id alone is insufficient: issuer and sub must match. A configuration change requires the normal reviewed re-pin and restart; logout, idle/absolute expiry and provider refusal use live Q175 checks on each HTTP request. No Console principal or cap is cached between requests. Each preview and final write spawns a fresh wrapper with a fresh nonce.

The verifier returns owner provenance including via=console and the subject only after those checks. A separate trusted binder issues an internal transient Console cap restricted to the preview and Console resolution operations below. Do not weaken today's bindHuman or general #human gate to accept via=console for every owner operation. CLI, user, tester, reader, launch and seat caps cannot use the Console resolution operation, and a Console cap cannot invoke other owner writes. The cap never leaves the broker and ends with the connection.

The proof trusts the verified Console's mapping, as row 196 explicitly permits. The bus does not independently revalidate an ID token. A hostile process on the instance uid can inspect memory or interfere with same-uid state; this is not a wall against that process. Separate uids narrow cross-instance reach only. The row 196 provenance statement remains unchanged:

The Console provenance option trusts verified code and process metadata, not an independent bus-side OIDC exchange. That trade must be approved, not hidden behind the phrase zero trust.

3. Write path and evidence

A signed-in human opens an eligible decision and chooses Approve or Deny. POST /api/decisions/ID/confirmation asks for a confirmation view. After all HTTP guards, a fresh Console proof calls a read-only decision.preview.console bus operation. The broker returns the current eligibility and digest. The Console creates a random 256-bit confirmation token held only in server memory as a hash. It binds the token to this live session, business, decision, exact choice and digest, expiring after 120 seconds. Bound the store to 1024 entries; refuse a new confirmation at capacity, rather than evict a live confirmation. No bus write, grant, seen event or resolution occurs at this step.

The confirmation view shows the decision id, question, selected real option text, grant method/target and consequences. The human must click a second, explicit Confirm approve or Confirm deny. Cancel sends no resolution. No modal or notification opening resolves a decision. Render all content as text with the existing escaping rules, never as trusted markup.

POST /api/decisions/ID/resolve takes only choice and confirmation. The Console rechecks the live session and HTTP guards, matches and consumes that session's confirmation once before awaiting the bus, then spawns a fresh wrapper. The restricted operation decision.resolve.console carries id, choice and the expected digest. The browser cannot submit via, human, provider, issuer, sub, grant fields, a principal or a role. Those fields are refused, not ignored.

The broker rechecks restricted Console identity, business, authoritative grant eligibility, current option and digest, and open status in the same transaction that appends the resolution. This operation shares the existing decision.resolve transaction and notification behavior rather than duplicate that machinery. Only its explicit provenance/eligibility gates differ. Existing CLI decide and role resolution keep their current authority and evidence.

Evidence is append-only. decision_events.by stays the configured business human and decision_events.via becomes console. The accompanying human.input event in the same transaction records decision, choice, op=resolved, via=console and the subject object {provider, iss, sub}, with a reference to the decision event's sequence. Trail output shows this provenance. Do not put the subject in a browser-supplied note or replace the human id with a display name. No token, nonce, confirmation value or cookie is logged. This uses existing event JSON; no new schema column is required for the subject.

Current #approvedGrant requires via=cli. It must explicitly accept via=console only when that exact decision event has matching trusted Console human.input provenance, owner and subject under this design. Merely widening its via string check is insufficient. CLI proofs remain valid as before. Existing grant single-consumption and executor rechecks remain authoritative, including the host and host-enroll starts after commit. Deny, refusal and failed transactions start no executor. Tests must cover this guard, since a UI success with no usable grant would fail J2 just as an unauthorized grant would.

4. Guards, concurrency and refusal contract

The main listener requires --sso and --send for these routes. --no-send is a release-tool choice that produces a unit without --send. Read-only mode rejects both confirmation and resolve. The tester listener never offers either route. Proxy preview mode, loopback owner access without SSO and a seat credential do not enable them. Q175 session and Host guards run before any decision lookup.

POST requires one exact Origin equal to the configured HTTPS public origin, one Sec-Fetch-Site equal to same-origin, and application/json. No CORS, GET mutation, form-encoded body, absent metadata or duplicate header acceptance. Use the existing small JSON body limit and strict field validation. The confirmation token is an additional session-bound action guard, not a reusable identity credential. Neither confirmation nor resolution trusts a Referer.

Condition HTTP/code Message
Missing, expired, logged-out or refused session 401 sign-in-required Sign in again before answering.
Without --sso, without --send, or --no-send 403 read-only Console decision answers are not enabled. Use mosaic decide.
Wrong/repeated Origin, wrong/missing fetch metadata 403 cross-origin Answer from the signed-in Console page.
Tester route 404 not-found Not found.
Agent, seat, user, wrong parent/uid, unknown owner subject 403 human-required The bus refused this human identity.
Peer helper failure 403 peercred-required The bus could not verify this connection.
Wrong method on a main Console decision endpoint 405 method-not-allowed Use POST.
Wrong content type, malformed JSON, unknown/body identity fields 400 invalid-request Invalid decision answer.
Body over existing limit 413 request-too-large Decision answer is too large.
Decision absent or in another business 404 decision-not-found This decision is unavailable.
Open decision outside this grant-only slice 403 decision-not-eligible Answer this decision with mosaic decide.
Decision closed, superseded or concurrently resolved 409 decision-closed This decision is no longer open. Refresh the inbox.
Option removed/changed or digest changed 409 decision-stale The choices changed. Review the decision again.
Missing, expired, consumed or mismatched confirmation 409 confirmation-required Review and confirm this answer again.
Confirmation store full 503 confirmation-unavailable Confirmation is unavailable. Try again later.
No bus or lost response after submission 503 outcome-unknown The answer may have reached the bus. Refresh before trying again.

The public messages above are the endpoint contract; map existing bus refusal names explicitly where they differ. No 200 for a refusal. A successful resolve returns the recorded decision id, choice and resolution state, plus grant workflow status if returned by the broker. The UI disables both action buttons while submitting. A second click cannot reuse a consumed confirmation; a concurrent fresh confirmation still loses at the broker's closed-state check. Only one resolution event, human.input event, notification and grant start may result. On uncertain transport, never retry automatically. Refresh reads the actual result; a different unresolved answer requires fresh confirmation.

Expiry/logout before either POST refuses. A logout racing an already-admitted bus transaction cannot cancel an effect already committed; no claim to the contrary is made. Session checks immediately before spawning bound this limit.

5. Inbox without SSO and read-only presentation

Hide the buttons completely without --sso. Keep the exact copyable mosaic decide lines and explain that Console answers need sign-in and writes enabled. Under SSO but without --send, also show the terminal lines and read-only explanation. Do not present a disabled Approve button that suggests sign-in alone grants write authority. With SSO and send enabled, only eligible grant decisions gain the two controls. Non-grant decisions keep terminal lines. Closed decisions show the recorded answer and provenance, with no action controls or confirmation.

Server-provided UI capabilities are presentation only. Direct POSTs receive all the same guards. A stale page cannot restore a session, write mode or decision. The live instance stays unchanged until Jason's phase 2 window and an authorized re-pin whose tree includes this row and its documented flag meaning.

6. Stand-in tests, mutants and landing gates

Use row 192's fake OIDC provider, synthetic subjects and scratch HTTP listeners; use the real test bus and row 196 kernel-peer fixtures. Never use the live provider, origin, ports, credentials, units or instance roots. All scratch state uses the approved /mnt/storage/scratch/tmp TMPDIR. No real second uid.

Evidence Required cases Mutants
Eligibility bound grant, two actual keys, other decisions/technical/roles/ambiguous options hidden and POST refused J1 trust browser eligibility; J2 hardcode yes/no
Owner provenance live fake OIDC owner works; header/name/body/seat/user impersonation, agent parent, other tree, bad nonce and wrong peer refuse J3 use name/header; J4 skip Console-parent walk; J5 accept other nonce namespace
Request lifetime new proof per preview/resolve; session replaced/expired/logged out refuses; cap never returned and releases on success/failure/close J6 reuse prior session/principal; J7 leak cap
HTTP and confirmation all refusal table cases; missing/duplicate Origin and metadata, token from another session/decision/choice, expiry, capacity, cancel and direct POST J8 skip CSRF; J9 accept unconfirmed write; J10 unbind confirmation
Business and races foreign business, closed decision, stale digest/key, parallel confirmations, double click and lost reply; exactly one durable result/notification J11 skip business/digest/closed check; J12 permit confirmation reuse
Evidence and grant effect via=console plus verified subject in same transaction, CLI unchanged; approval consumable once by existing grant path, deny/refusal no executor J13 write cli or omit subject; J14 widen via without provenance; J15 execute on deny
UI/browser hidden without SSO/send, terminal fallback, escaped text, confirm/cancel, pending state, stale/error refresh, no automatic retry J16 enable without SSO/send; J17 auto-submit or retry

Browser tests use the repository's isolated fixture infrastructure. The reviewer must inspect which runtime/UI boundary each mutant actually weakens. Record restored hashes and clean Git status for each. Suites and mutant batches need Sage's slot; stop/report under mos-0823. Final acceptance is Webby's approved manifest and Sage's whole bus/WebUI/CLI and scripts/test-*.sh gate.

Before implementation, Webby must approve this design and the REQ-WEB-2 / REQ-DEC-3 amendment must be landed through Mos and Jason. The PRD currently says human resolution is CLI-only. Decision 00ed58e2 reserves the Console amendment; this design does not edit the PRD or treat its reservation as landed policy. Row 252 code branches from row 196's reviewed landing and keeps its own review and gate. No live enablement, reachability change or independent auth mechanism.