@hellix-ai/cubes 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# cubes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Attach to your [Cubes](https://cubes.hellix.ai) sessions from your own terminal (Warp, iTerm2, Ghostty,
+Terminal.app, anything) with your own font, colors and keyboard shortcuts.
+
+```sh
+npm install -g @hellix-ai/cubes      # needs Node.js 22.4+
+
+cubes login --host cubes.hellix.ai   # prints a code; approve it in the browser
+cubes ls                             # your sessions
+cubes attach                         # pick a running one
+cubes attach 7ff4                    # or name one: an id prefix, or part of its title
+```
+
+No install: `npx @hellix-ai/cubes attach <session>`.
+
+## While attached
+
+Every key goes to the session, exactly as if Claude Code were running locally, except:
+
+| key | does |
+| --- | --- |
+| `Ctrl-]` | detach. The session keeps running. |
+| `Ctrl-V` | paste the image on your clipboard: it is uploaded to the session and its path typed in (macOS, and Linux with `wl-paste` or `xclip`). With no image on the clipboard, Ctrl-V goes through unchanged. |
+
+**One keyboard per session.** Attaching takes the keyboard from any browser tab open on the same session
+(that tab becomes read-only, with a Take over button) and fits the session to your window. If someone
+takes it back, the terminal says so and goes read-only; detach and attach again to reclaim it.
+`cubes attach --view` watches without taking it.
+
+A stopped or hibernated session is resumed before attaching (`--no-resume` to refuse). A dropped
+connection reconnects on its own and replays the screen.
+
+Scrollback lives in the session's tmux: scroll with the mouse wheel or trackpad (tmux copy-mode), not
+your terminal's own scrollback.
+
+## Commands
+
+```
+cubes login [--host URL] [--org ALIAS] [--no-browser]
+cubes logout
+cubes whoami
+cubes org [ALIAS]
+cubes ls [--all] [--json]
+cubes attach [SESSION] [--view] [--no-resume]
+```
+
+`--org ALIAS` works on any command. If you belong to several organizations, `cubes org` lists them and
+`cubes org <alias>` changes the default.
+
+## Sign-in
+
+`cubes login` uses the OAuth device flow against your Cubes install's own sign-in: the CLI never sees your
+password. The login is stored in `~/.config/cubes/config.json` (mode 0600) and lasts until you
+`cubes logout`, which revokes it, or until it goes unused for 30 days.
+
+For scripts and CI, skip the stored login: set `CUBES_HOST`, `CUBES_TOKEN` (an access token) and
+optionally `CUBES_ORG`.

package/dist/api.js

@@ -0,0 +1,58 @@
+// The REST half: the same routes the web app calls, with the same Bearer + `x-org` pair.
+import { CliError } from "./auth.js";
+export function makeApi(s, fetchImpl = fetch) {
+    async function call(method, path, body, init) {
+        const send = async (force) => {
+            const headers = { authorization: `Bearer ${await s.token(force)}` };
+            if (s.org)
+                headers["x-org"] = s.org;
+            let payload;
+            if (init?.raw) {
+                headers["content-type"] = init.contentType ?? "application/octet-stream";
+                payload = init.raw;
+            }
+            else if (body !== undefined) {
+                headers["content-type"] = "application/json";
+                payload = JSON.stringify(body);
+            }
+            try {
+                return await fetchImpl(`${s.host}/api${path}`, { method, headers, body: payload });
+            }
+            catch (e) {
+                throw new CliError(`cannot reach ${s.host}: ${e.message}`);
+            }
+        };
+        let res = await send(false);
+        // A token the server refuses may simply be one our clock thinks is still good. One forced
+        // refresh, then the refusal stands.
+        if (res.status === 401)
+            res = await send(true);
+        const text = await res.text();
+        let data = undefined;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch { /* not JSON */ }
+        if (!res.ok) {
+            const msg = data?.error;
+            throw new ApiError(res.status, typeof msg === "string" ? msg : `HTTP ${res.status}`, path);
+        }
+        return data;
+    }
+    return {
+        get: (path) => call("GET", path),
+        post: (path, body, init) => call("POST", path, body, init),
+    };
+}
+export class ApiError extends CliError {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(status === 400 && /organization/.test(message)
+            ? `${message} - pick one with \`cubes org <alias>\``
+            : message);
+        this.status = status;
+        this.path = path;
+        this.name = "ApiError";
+    }
+}

package/dist/args.js

@@ -0,0 +1,37 @@
+// Argument parsing, small enough not to need a dependency.
+import { CliError } from "./auth.js";
+/** Flags that take a value (`--host X` or `--host=X`); every other flag is a switch. */
+const VALUED = new Set(["host", "org"]);
+export function parseArgs(argv) {
+    const pos = [];
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h") {
+            flags.set("help", true);
+            continue;
+        }
+        if (a === "-v") {
+            flags.set("version", true);
+            continue;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+            if (eq > 0)
+                flags.set(name, a.slice(eq + 1));
+            else if (VALUED.has(name)) {
+                const v = argv[i + 1];
+                if (v === undefined || v.startsWith("--"))
+                    throw new CliError(`--${name} needs a value`);
+                flags.set(name, v);
+                i++;
+            }
+            else
+                flags.set(name, true);
+            continue;
+        }
+        pos.push(a);
+    }
+    return { cmd: pos.shift(), pos, flags };
+}

package/dist/attach.js

@@ -0,0 +1,318 @@
+// The bridge: your terminal <-> the session's live TTY, over the same websocket the web terminal uses.
+//
+// The wire (server/src/ws.ts + engine/tty.ts) is already exactly what a terminal needs:
+//   • the upgrade carries a single-use ~30s ticket as the SECOND subprotocol, after the constant
+//     `cube.tty.v1` (the server echoes only the marker, never the secret);
+//   • BINARY frames are raw terminal bytes - our keystrokes in, the screen out;
+//   • TEXT frames are JSON control: we send {type:'resize'|'takeover'}, the server sends
+//     {type:'role', writer, cols, rows} and {type:'resize', cols, rows}.
+// So there is nothing to emulate here. Raw mode on, bytes both ways, a resize on SIGWINCH.
+//
+// ONE KEYBOARD PER SESSION. The server gives the writer token to the first viewer and makes every
+// later one a read-only mirror. Someone who runs `cubes attach` means to type, so unless `--view` is
+// passed we send `takeover` the moment we are told we are a mirror - the same button the web shows
+// on a read-only tile. The writer also decides the pane's size, so the session re-fits to THIS window.
+import { ApiError } from "./api.js";
+import { InputFilter, PASTE_IMAGE_BYTE } from "./keys.js";
+export const TTY_SUBPROTOCOL = "cube.tty.v1";
+const OPEN = 1;
+/** Close codes (server/src/engine/tty.ts, web/src/cubes/Terminal.tsx). */
+const WS_CLOSE_BACKPRESSURE = 4001;
+const WS_CLOSE_FULL = 4002;
+const WS_CLOSE_PARKED = 4004;
+const WS_CLOSE_UNAUTHORIZED = 4403;
+/** Drops that mean "the session is fine, the socket is not": re-mint a ticket and re-attach; the
+ *  server replays its scrollback ring. 1001/1012/1013 are a server going away or restarting. */
+const TRANSIENT = new Set([WS_CLOSE_BACKPRESSURE, 1001, 1005, 1006, 1011, 1012, 1013]);
+const DEFAULT_BACKOFF = [300, 600, 1200, 2400, 5000, 5000, 5000, 5000];
+/** Everything an attached session may have switched on in YOUR terminal (mouse reporting, bracketed
+ *  paste, focus events, app cursor keys, kitty/modifyOtherKeys keyboard modes, a hidden cursor, a
+ *  scroll region) - switched back off on the way out, so detaching never leaves Warp/iTerm in a
+ *  state where the wheel prints garbage. */
+export const RESTORE_TERMINAL = "\x1b[0m\x1b[?25h\x1b[0 q\x1b[r" +
+    "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l" +
+    "\x1b[?2004l\x1b[?1004l\x1b[?1l\x1b>\x1b[<u\x1b[>4;0m";
+const ENTER_ALT = "\x1b[?1049h\x1b[H\x1b[2J";
+const LEAVE_ALT = "\x1b[?1049l";
+const CLEAR = "\x1b[H\x1b[2J";
+export function wsUrlFor(host, id) {
+    return `${host.replace(/^http/i, "ws")}/api/sessions/${encodeURIComponent(id)}/tty`;
+}
+export function attach(deps, session, opts = {}) {
+    const { api, stdin, stdout, stderr } = deps;
+    const backoff = opts.backoffMs ?? DEFAULT_BACKOFF;
+    const filter = new InputFilter({ pasteImage: !opts.view });
+    const enc = new TextEncoder();
+    return new Promise((resolve) => {
+        let ws = null;
+        let role = null;
+        let askedTakeover = false;
+        let takeoverPending = false;
+        /** Someone took the keyboard FROM us. Sticky for the whole attach, reconnects included: a person
+         *  who clicked "take over" in the browser must not have it snatched back by a network blip. */
+        let yielded = false;
+        let entered = false;
+        let done = false;
+        let attempts = 0;
+        let timer = null;
+        // Keystrokes that must wait their turn: until the server says who holds the keyboard, and while
+        // an image paste is uploading (so what is typed after Ctrl-V lands after the path, not before).
+        let pending = [];
+        let pasting = false;
+        const note = (msg) => {
+            stderr.write(entered ? `\r\n\x1b[2m[cubes] ${msg}\x1b[0m\r\n` : `[cubes] ${msg}\n`);
+        };
+        const enter = () => {
+            if (entered)
+                return;
+            entered = true;
+            if (stdin.isTTY)
+                stdin.setRawMode?.(true);
+            stdout.write(ENTER_ALT);
+        };
+        const finish = (code, message) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            stdin.off("data", onData);
+            stdout.off("resize", onResize);
+            const sock = ws;
+            ws = null;
+            if (sock) {
+                sock.onclose = null;
+                sock.onmessage = null;
+                try {
+                    sock.close(1000, "detached");
+                }
+                catch { /* already gone */ }
+            }
+            if (entered) {
+                stdout.write(RESTORE_TERMINAL + LEAVE_ALT);
+                if (stdin.isTTY)
+                    stdin.setRawMode?.(false);
+            }
+            stdin.pause();
+            resolve({ code, message });
+        };
+        const sendRaw = (b) => {
+            if (ws && ws.readyState === OPEN)
+                ws.send(b);
+        };
+        // Hold keys while we cannot yet say where they go: before the first role, while our takeover is
+        // in flight (a mirror that asked for the keyboard is about to be the writer), and mid-paste.
+        const holding = () => role === null || (role === "mirror" && takeoverPending) || pasting;
+        const flushPending = () => {
+            if (holding())
+                return;
+            const q = pending;
+            pending = [];
+            if (role === "writer")
+                for (const b of q)
+                    sendRaw(b);
+        };
+        const sendInput = (b) => {
+            if (opts.view)
+                return;
+            if (holding()) {
+                if (pending.reduce((n, x) => n + x.length, 0) < 64 * 1024)
+                    pending.push(b.slice());
+                return;
+            }
+            if (role === "writer")
+                sendRaw(b);
+        };
+        const sendResize = () => {
+            const cols = stdout.columns ?? 80;
+            const rows = stdout.rows ?? 24;
+            if (ws && ws.readyState === OPEN)
+                ws.send(JSON.stringify({ type: "resize", cols, rows }));
+        };
+        const pasteImage = async () => {
+            pasting = true;
+            let typed = Uint8Array.of(PASTE_IMAGE_BYTE);
+            try {
+                const img = await deps.readClipboardImage();
+                if (img) {
+                    note(`uploading the image on your clipboard (${Math.ceil(img.bytes.length / 1024)} KB)…`);
+                    const r = await api.post(`/sessions/${encodeURIComponent(session.id)}/paste-image`, undefined, { contentType: img.type, raw: img.bytes });
+                    // A trailing space so the person can keep typing after the path - the web does the same.
+                    typed = enc.encode(r.path + " ");
+                }
+            }
+            catch (e) {
+                note(`image paste failed: ${e.message}`);
+                typed = new Uint8Array(0);
+            }
+            finally {
+                pasting = false;
+            }
+            if (done)
+                return;
+            if (typed.length) {
+                if (role === "writer")
+                    sendRaw(typed);
+                else
+                    pending.unshift(typed);
+            }
+            flushPending();
+        };
+        function onData(chunk) {
+            for (const a of filter.feed(chunk)) {
+                if (a.kind === "detach") {
+                    finish(0, "detached");
+                    return;
+                }
+                if (a.kind === "paste-image") {
+                    if (pasting)
+                        continue;
+                    void pasteImage();
+                    continue;
+                }
+                sendInput(a.bytes);
+            }
+        }
+        function onResize() { sendResize(); }
+        const retry = (ms) => {
+            if (done)
+                return;
+            timer = setTimeout(() => { timer = null; void connect(); }, ms);
+        };
+        const onClose = (code, reason) => {
+            ws = null;
+            role = null;
+            if (done)
+                return;
+            if (code === 1000) {
+                finish(0, reason ? `session ended (${reason})` : "session ended");
+                return;
+            }
+            if (code === WS_CLOSE_UNAUTHORIZED) {
+                finish(1, "the server refused the attach - your sign-in or org membership may have changed");
+                return;
+            }
+            if (code === WS_CLOSE_PARKED) {
+                note("this session's terminal is parked (its machine stopped answering). Waiting for it to come back - Ctrl-] to give up.");
+                retry(opts.parkedRetryMs ?? 15_000);
+                return;
+            }
+            if (code === WS_CLOSE_FULL) {
+                note("this session already has the most viewers it allows - waiting for one to leave. Ctrl-] to give up.");
+                retry(opts.fullRetryMs ?? 5_000);
+                return;
+            }
+            if (TRANSIENT.has(code) && attempts < backoff.length) {
+                const ms = backoff[attempts];
+                attempts += 1;
+                note(`connection dropped (${code}) - reconnecting (${attempts}/${backoff.length})…`);
+                retry(ms);
+                return;
+            }
+            finish(1, TRANSIENT.has(code)
+                ? "lost the connection to the session and could not get it back"
+                : `the session closed the connection (${code}${reason ? ` ${reason}` : ""})`);
+        };
+        const connect = async () => {
+            if (done)
+                return;
+            let ticket;
+            try {
+                ticket = (await api.post(`/sessions/${encodeURIComponent(session.id)}/terminal/ticket`)).ticket;
+            }
+            catch (e) {
+                if (done)
+                    return;
+                if (e instanceof ApiError && e.status === 409) {
+                    finish(1, "the session is not running any more");
+                    return;
+                }
+                if (e instanceof ApiError && e.status < 500) {
+                    finish(1, e.message);
+                    return;
+                }
+                // The server itself is restarting or unreachable: same ladder as a dropped socket.
+                if (attempts < backoff.length) {
+                    const ms = backoff[attempts];
+                    attempts += 1;
+                    note(`${e.message} - retrying (${attempts}/${backoff.length})…`);
+                    retry(ms);
+                    return;
+                }
+                finish(1, e.message);
+                return;
+            }
+            if (done)
+                return;
+            const sock = deps.openWs(wsUrlFor(deps.host, session.id), [TTY_SUBPROTOCOL, ticket]);
+            sock.binaryType = "arraybuffer";
+            ws = sock;
+            askedTakeover = false;
+            takeoverPending = false;
+            sock.onopen = () => {
+                if (ws !== sock)
+                    return;
+                if (!entered)
+                    enter();
+                else
+                    stdout.write(CLEAR); // the server replays its ring; paint it on a clean screen
+                sendResize();
+            };
+            sock.onmessage = (ev) => {
+                if (ws !== sock)
+                    return;
+                const data = ev.data;
+                if (typeof data === "string") {
+                    let msg;
+                    try {
+                        msg = JSON.parse(data);
+                    }
+                    catch {
+                        return;
+                    }
+                    if (msg.type === "role") {
+                        // A role is what proves the attach stuck (the viewer-cap refusal arrives AFTER open),
+                        // so this - not onopen - is where the reconnect ladder resets.
+                        attempts = 0;
+                        const prev = role;
+                        role = msg.writer ? "writer" : "mirror";
+                        if (role === "mirror" && prev === "writer") {
+                            // Demoted: another viewer took the keyboard. Never take it back automatically - two
+                            // terminals that each did would pass it back and forth forever.
+                            yielded = true;
+                            takeoverPending = false;
+                            note("someone else took the keyboard - this terminal is read-only now. Ctrl-] and attach again to take it back.");
+                        }
+                        else if (role === "mirror" && !opts.view && !askedTakeover && !yielded) {
+                            askedTakeover = true;
+                            takeoverPending = true;
+                            sock.send(JSON.stringify({ type: "takeover" }));
+                        }
+                        if (role === "writer") {
+                            takeoverPending = false;
+                            sendResize(); // the pane now sizes to us
+                        }
+                        flushPending();
+                    }
+                    return;
+                }
+                if (data instanceof ArrayBuffer)
+                    stdout.write(new Uint8Array(data));
+                else if (ArrayBuffer.isView(data))
+                    stdout.write(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+            };
+            sock.onclose = (ev) => { if (ws === sock)
+                onClose(ev.code, ev.reason); };
+            sock.onerror = () => { };
+        };
+        stdin.on("data", onData);
+        stdout.on("resize", onResize);
+        stdin.resume();
+        if (opts.signal?.aborted) {
+            finish(0, "detached");
+            return;
+        }
+        opts.signal?.addEventListener("abort", () => finish(0, "detached"), { once: true });
+        void connect();
+    });
+}

package/dist/auth.js

@@ -0,0 +1,206 @@
+// Signing in: the OAuth 2.0 Device Authorization Grant (RFC 8628) against the app's own Keycloak.
+//
+// The CLI is told nothing but the app's URL. `/api/client-config` names the realm issuer and the
+// public client (`cubes-cli`), the issuer's discovery document names the endpoints, and the person
+// approves a short code in the browser where they are already signed in. So the CLI never sees a
+// password, a Google login never has to happen inside a terminal, and the same binary works against
+// any install.
+//
+// It asks for `offline_access`: a laptop CLI is used in bursts days apart, and an ordinary refresh
+// token dies with the browser-length SSO session. `cubes logout` revokes the offline token.
+import { loadLogin, saveLogin } from "./config.js";
+export const SCOPE = "openid profile email organization offline_access";
+/** Refresh this long before the access token actually expires, so a request never races the edge. */
+const EXP_SKEW_S = 60;
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}
+export function normalizeHost(raw) {
+    let h = raw.trim();
+    if (!/^https?:\/\//i.test(h))
+        h = `https://${h}`;
+    const u = new URL(h);
+    return u.origin;
+}
+/** The payload of a JWT, unverified. Only ever used to read OUR OWN token's exp + display claims -
+ *  the server verifies every token it is handed; nothing here makes an authorization decision. */
+export function decodeJwt(token) {
+    const part = token.split(".")[1];
+    if (!part)
+        return {};
+    try {
+        return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The org aliases a token is a member of. Keycloak's membership mapper emits a flat string array;
+ *  it can also be configured to emit an object keyed by alias, so both are read. */
+export function orgsOf(token) {
+    const c = decodeJwt(token).organization;
+    if (Array.isArray(c))
+        return c.filter((x) => typeof x === "string");
+    if (c && typeof c === "object")
+        return Object.keys(c);
+    return [];
+}
+export function whoOf(token) {
+    const p = decodeJwt(token);
+    const name = p.preferred_username ?? p.email ?? p.sub;
+    return typeof name === "string" ? name : "unknown";
+}
+async function json(res, what) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${what}: HTTP ${res.status} (not JSON)`);
+    }
+}
+export async function discover(host) {
+    let res;
+    try {
+        res = await fetch(`${host}/api/client-config`);
+    }
+    catch (e) {
+        throw new CliError(`cannot reach ${host}: ${e.message}`);
+    }
+    if (!res.ok)
+        throw new CliError(`${host} did not answer /api/client-config (HTTP ${res.status}) - is that a Cubes URL?`);
+    const cfg = await json(res, "client-config");
+    if (cfg.cli === undefined)
+        throw new CliError(`${host} is too old for the CLI (no login settings in /api/client-config)`);
+    if (cfg.cli === null)
+        throw new CliError(`${host} has no sign-in configured`);
+    const wk = await fetch(`${cfg.cli.issuer}/.well-known/openid-configuration`);
+    if (!wk.ok)
+        throw new CliError(`cannot read the sign-in settings at ${cfg.cli.issuer} (HTTP ${wk.status})`);
+    const d = await json(wk, "openid-configuration");
+    if (!d.device_authorization_endpoint)
+        throw new CliError("this install's sign-in does not support device login");
+    return {
+        issuer: cfg.cli.issuer,
+        clientId: cfg.cli.clientId,
+        endpoints: { token: d.token_endpoint, device: d.device_authorization_endpoint, revoke: d.revocation_endpoint },
+    };
+}
+export async function startDevice(d) {
+    const res = await fetch(d.endpoints.device, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ client_id: d.clientId, scope: SCOPE }),
+    });
+    const body = await json(res, "device login");
+    if (!res.ok || !body.device_code) {
+        throw new CliError(`device login refused: ${body.error_description ?? body.error ?? `HTTP ${res.status}`}`);
+    }
+    return body;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Poll the token endpoint until the person approves (or refuses, or the code expires). */
+export async function pollDevice(d, start) {
+    let interval = Math.max(1, start.interval ?? 5) * 1000;
+    const deadline = Date.now() + start.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const res = await fetch(d.endpoints.token, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: start.device_code,
+                client_id: d.clientId,
+            }),
+        });
+        const t = await json(res, "token");
+        if (res.ok && t.access_token)
+            return t;
+        if (t.error === "authorization_pending")
+            continue;
+        if (t.error === "slow_down") {
+            interval += 5000;
+            continue;
+        }
+        if (t.error === "access_denied")
+            throw new CliError("sign-in was declined in the browser");
+        if (t.error === "expired_token")
+            break;
+        throw new CliError(`sign-in failed: ${t.error_description ?? t.error ?? `HTTP ${res.status}`}`);
+    }
+    throw new CliError("the code expired before it was approved - run `cubes login` again");
+}
+export function loginFromTokens(host, d, t, org) {
+    if (!t.access_token || !t.refresh_token)
+        throw new CliError("sign-in returned no tokens");
+    const exp = decodeJwt(t.access_token).exp;
+    return {
+        host, issuer: d.issuer, clientId: d.clientId, endpoints: d.endpoints,
+        refreshToken: t.refresh_token, accessToken: t.access_token,
+        accessExp: typeof exp === "number" ? exp : Math.floor(Date.now() / 1000) + (t.expires_in ?? 300),
+        org,
+    };
+}
+export async function refresh(login) {
+    const res = await fetch(login.endpoints.token, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: login.refreshToken, client_id: login.clientId }),
+    });
+    const t = await json(res, "token refresh");
+    if (!res.ok || !t.access_token) {
+        throw new CliError(`your sign-in to ${login.host} has expired or was revoked - run \`cubes login\``);
+    }
+    const exp = decodeJwt(t.access_token).exp;
+    return {
+        ...login,
+        accessToken: t.access_token,
+        // Keycloak may or may not rotate; keep the old one when it does not send a new one.
+        refreshToken: t.refresh_token ?? login.refreshToken,
+        accessExp: typeof exp === "number" ? exp : Math.floor(Date.now() / 1000) + (t.expires_in ?? 300),
+    };
+}
+export async function revoke(login) {
+    if (!login.endpoints.revoke)
+        return;
+    await fetch(login.endpoints.revoke, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ token: login.refreshToken, token_type_hint: "refresh_token", client_id: login.clientId }),
+    }).catch(() => undefined);
+}
+/** The login a command runs under. `CUBES_TOKEN` (+ `CUBES_HOST`, `CUBES_ORG`) bypasses the stored
+ *  login entirely - for CI and scripts, where nobody is there to approve a device code. */
+export function currentSession(opts = {}, env = process.env) {
+    if (env.CUBES_TOKEN) {
+        const tok = env.CUBES_TOKEN;
+        if (!env.CUBES_HOST)
+            throw new CliError("CUBES_TOKEN needs CUBES_HOST too");
+        const host = normalizeHost(env.CUBES_HOST);
+        const org = opts.org || env.CUBES_ORG || orgsOf(tok)[0];
+        return { host, org, token: async () => tok, who: () => whoOf(tok) };
+    }
+    let login = loadLogin();
+    if (!login)
+        throw new CliError("not signed in - run `cubes login --host <your Cubes URL>`");
+    const org = opts.org || env.CUBES_ORG || login.org;
+    return {
+        host: login.host,
+        org,
+        async token(force = false) {
+            const now = Math.floor(Date.now() / 1000);
+            if (!force && login.accessToken && (login.accessExp ?? 0) - EXP_SKEW_S > now)
+                return login.accessToken;
+            login = await refresh(login);
+            saveLogin(login);
+            return login.accessToken;
+        },
+        who: () => (login.accessToken ? whoOf(login.accessToken) : "unknown"),
+    };
+}