ADR-0032 Architecture decision record
The Console unlocks with a Caller's credential, and shows what its scopes allow
ADR-0014 built the HTTP surface on one premise: the visualizer page is a browser, and a browser holds no token — so it got a projection instead of a credential, and "give the page a token" was explicitly rejected. That page is now the Console: it starts runs, answers Gates and cancels runs, which are writes on the guarded surface. This ADR records how a browser earns those writes without moving the open band. The person presents a credential; the page never ships with one.
Decision
- The person presents a Caller's credential; the page never ships with one. The Console's nav carries a password field, and a login button for each JWT issuer that the Instance declares with
login: true(ADR-0078). Empty, the page is precisely ADR-0014's observer: open structure and observation, no control rendered. With a credential, the page sendsAuthorization: Beareron the guarded surface. The credential is any Caller's: the Instance token, a named Caller token, or a JWT. The login gets a JWT from the issuer with OIDC (the authorization code flow with PKCE, as a public client), and the page then uses it as it uses a typed token. The page as served stays open and inert; ADR-0014's rejection stands, because what it rejected was baking the credential into the page. - The login's facts come from an open route, and its client id is the issuer's
audience. Before a login, the page readsGET /console/config:{ login: [{ issuer, clientId }] }, from the issuers of the current Assembly that havelogin: true. The route is in the open band (ADR-0014), because the page reads it before it holds a credential, and both values are public: a public client has no secret, and the issuer's URL is in every JWT that it signs. The client id is the issuer entry'saudience, because the JWT that the login gives names its client as its audience, and that is what the JWT authenticator checks. A login is opt-in for each issuer, because an issuer for machines (a CI provider's tokens) has no login page. The page reads the issuer's discovery document, asks foropenid,profile,emailandgroupswhere the issuer lists each, and sends the ID token as the bearer: an access token's audience and form differ between providers. The return address is always the Console's root (/), so the client registers one redirect URI; the page then puts the address back to where the login began. The verifier, the state and that address wait insessionStorageuntil the return, and a return whose state does not match is refused. PKCE needscrypto.subtle, so a login needs the Console on https or on localhost, and the issuer must let the Console's origin call its discovery document and its token endpoint (CORS). - The page shows only what the Caller's scopes allow. On entry the page asks
GET /whoamifor the Caller record: its name, the name that jr2 shows, and its scopes for each Workflow. It renders a control only where a scope opens its route: the start form withstartfor that Workflow, Gate cards withanswer, cancel withcancel, a run's full state withread, and the Steering box withsteer. The page re-fetches a run on a frame only for a Caller withanswerorreadon its Workflow. The nav shows who the page acts as: the name that jr2 shows, else<via>/<name>, with the scopes in its title, and a sign-out button in place of the field. The server still checks each request (ADR-0014); the page hides a control so that a person does not meet a 403, not as a guard. - The credential lives in
sessionStorage— survives a reload, dies with the tab, never a cookie (no ambient credential, no CSRF surface). A typed token and a login's JWT live there alike. A later 401 (an expired JWT, a rotated token) drops the UI back to observer mode rather than failing per widget. - Gate discovery is a frame-triggered guarded read, not an open-band extension. A Gate exists exactly while its invoking state is entered (ADR-0011), and every entry/exit lands a status frame on the open workflow feed (ADR-0022) — so a Console whose Caller has
answerreadsGET /gateson entry and again on each frame, and folds the Gates into its store.GET /gateslists only the Gates that the Caller may answer, across every Workflow (ADR-0078), so the Gate cards are the person's inbox and never show a Gate the person cannot answer. Synchronized, no polling loop, and the observation projection is untouched. A delivery's success is likewise confirmed by the next frame emptying the card, never by local bookkeeping. - The rail lists ended runs too. It lists the live runs and, under them, the ended runs of the selected Workflow from
GET /runs?status=ended&workflow=<name>(ADR-0009), each with its status, and adriftedrun with its reason (ADR-0030). An ended run opens as a live one does: its graph, its last status and its conversations, for as long as jr2 keeps the run (ADR-0065). A run on an older Assembly carries the mark "older Assembly · <hash>" and is drawn on its own Machine, live or ended: an ended run's row names the Machine it ran on (ADR-0069). Adriftedrun has no Machine to draw, so it shows its drift reason in place of the graph. The Console shows each outstanding pick as "outstanding since". - A conversation opens in a bottom drawer. A full-width drawer across the bottom of the page shows the run's conversations (ADR-0023). A person can change its height, and the page keeps the height for that viewer. Closed, it is a bar of tabs, one for each Agent slot, with a dot on a slot whose Turn is live. Open, it shows the selected slot's conversation and follows a live Turn, with the Steering box beside it for a Caller with
steer. It reads the conversation routes, so it needsread. The right drawer keeps Attention and Activity. - Page addresses content-negotiate; JSON is the default dialect.
/and/workflows/:nameserve the Console shell toAccept: text/htmland JSON to everything else — so the workflow-detail resource keeps its natural address (the run-input schema's home, ADR-0033) and no future page has to squat on a mangled sibling path. Nothing existing moves: EventSource askstext/event-stream, and the Harness's Menu and the CLI never ask for HTML./viz/*is deleted (greenfield, no redirects); assets move to/assets/*, which also retires the "a workflow namedassetsis shadowed" hazard.
Considered options
jr2 ui— the CLI opens the browser through an authenticated local proxy. A convenience layer worth building on top of the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress, where the browser talks to the Service directly and the CLI is not in the path.- The Instance token alone. Rejected (ADR-0078): a person who must answer Gates and holds no cluster RBAC would then hold every act on every run. A scoped Caller's credential is what that person holds.
- The conversation in the right drawer. Rejected: a conversation needs the page's width, and the right drawer keeps Attention and Activity.
- Announce gates on the open observation feed (even just
{runId, gate}). Rejected: it widens the projection for a convenience the credential already solves, and the open band has an unresolved exposure question as it stands (spawn ids — the ADR-0014 open call). The projection stays the one place the line is drawn. - A
/uipath prefix, or moving the API under/api. Rejected for negotiation: the first is ceremony on the address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the ADR-0009/0013 route tables for cosmetics.
Consequences
- No new band. The server-side diff of the Console itself is: negotiate two addresses, serve the shell, retire
/viz/*, and serveGET /console/configin the open band. The scopes,GET /whoamiand the login's issuers are ADR-0078's. - Possession follows the credential. The Instance token stays one
kubectl get secretaway for whoever holds cluster RBAC; a named token is what its holder was given; a login is what the identity provider's groups grant. - The XSS caveat is the real one and is bounded by what the page is: a credential in
sessionStorageis readable by scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the constraint the viz page already lives under. - GLOSSARY.md: Console is a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
- The Console's UX gets a browser tier —
@console-tagged Cucumber scenarios holding a Playwright page, in@jr2/e2e, excluded from the default profile (ADR-0010 as amended). What the page believes stays unit-tested inconsole-store.test.ts, and the login's pure half inconsole-login.test.ts; the browser tier asserts what a user does and sees, and the login against Dex in a container (ADR-0078). The login scenario is also tagged@dex, because it needs docker, which the rest of the tier does not.