@basein/runner 0.1.0 → 0.2.0

package/dist/auth/client.js

@@ -1,31 +1,48 @@
 /**
- * auth client — ported from RRepeat's `src/auth/client.ts` (Phase 4.1).
+ * auth client — the CLI's session with the BaseIn service.
  *
- * Authenticates the CLI user against the BaseIn auth-service and returns a JWT
- * session. Every recording call carries that access token; the recording's owner
- * is the JWT subject on the server side, which is what makes tenancy work
- * without BaseInstRunner knowing anything about it.
+ * Every recording call carries an access token; the recording's owner is the
+ * JWT subject on the server side, which is what makes tenancy work without
+ * BaseInstRunner knowing anything about it.
+ *
+ * TWO HALVES, AND ONLY ONE OF THEM MAY PROMPT.
+ *
+ * `authenticate()` is the silent half, and every process calls it — `bir-hooks`
+ * at startup, each `bir-proxy`, and the CLI:
  *
- * Flow:
  *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
  *   2. If the access token is still valid, reuse it.
  *   3. Else if a refresh token is present, POST /auth/refresh (silent).
- *   4. Else prompt for email + password and POST /auth/login.
- *   5. Persist the result (mode 0600) and return it.
+ *   4. Else give up and return undefined.
+ *
+ * It used to have a fifth step — prompt for a password — and that had to go
+ * when sign-in moved to the browser. A device flow prints a code and waits up
+ * to ten minutes for someone to approve it in a browser; a control server doing
+ * that at startup, possibly under a supervisor where nobody can see the code,
+ * would hang instead of degrading. So interaction lives in `deviceLogin()`,
+ * which only `bir login` calls.
  *
- * WHY IT NEVER `process.exit`s: `bir-proxy` runs inside the host's process tree.
- * Failing to authenticate must degrade to not-recording (§10), not kill a server
- * the host is waiting on. Callers get `undefined` and decide.
+ * `deviceLogin()` is the interactive half: the OAuth 2.0 device authorization
+ * grant (RFC 8628). It mints a code, prints a link, and polls until the person
+ * approves in the console. It never handles a password, which is what makes it
+ * work for Google-only accounts — they have no password to type.
+ *
+ * WHY NOTHING HERE `process.exit`s: `bir-proxy` runs inside the host's process
+ * tree. Failing to authenticate must degrade to not-recording (§10), not kill a
+ * server the host is waiting on. Callers get `undefined` and decide.
  *
  * Config:
  *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
  *   BIR_AUTH_DISABLE  "1" to skip auth entirely (local dev / CI).
  */
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { configDir } from "../control/paths.js";
 import { join } from "node:path";
 import { logLine, errText } from "../util/log.js";
+import { packageVersion } from "../util/version.js";
 /**
  * Where the cached session lives.
  *
@@ -159,6 +176,65 @@ export async function normalizeAuthUrl(baseUrl, fetchImpl = fetch) {
     });
     return base;
 }
+/** How long the pre-flight `/health` probe may take. It is one small GET. */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * The hint printed whenever `BIR_AUTH_URL` turns out not to be the API. Kept in
+ * one place so `bir login`, `bir doctor` and the interactive prompt agree.
+ */
+export const AUTH_URL_HINT = "BIR_AUTH_URL must be the BaseIn API address (for example https://api.example.com), " +
+    "not the documentation or app website. Set it, then open a fresh terminal — " +
+    "an existing one keeps the value it started with";
+function causeText(err) {
+    const cause = err?.cause;
+    return cause?.code ?? cause?.message ?? errText(err);
+}
+/**
+ * Is there a BaseIn service at `baseUrl`? Returns `undefined` when there is,
+ * else one line saying what answered instead.
+ *
+ * WHY THIS EXISTS. Pointing `BIR_AUTH_URL` at the *website* instead of the API
+ * (`https://example.com` is the docs, `https://api.example.com` the service) is
+ * the easiest mistake to make and the hardest to read back: the static site
+ * answers `GET /health` with 200 and a page, so nothing objects until the
+ * password has already been POSTed to it and it says `405 Method Not Allowed`
+ * — a message about HTTP verbs, for a problem about hosts. Observed on a first
+ * sign-in; the user tried the app URL next and got a redirect.
+ *
+ * So, before anyone types a password: expect the health endpoint to answer
+ * with JSON. A website answers with HTML; a wrong port answers with nothing.
+ * The check is deliberately loose about the body — deployments differ — and
+ * strict about the content type, which is what separates a service from a page.
+ */
+export async function describeAuthService(baseUrl, fetchImpl = fetch) {
+    const base = baseUrl.replace(/\/+$/, "");
+    if (!base)
+        return "no URL configured";
+    let res;
+    try {
+        res = await fetchImpl(`${base}/health`, {
+            method: "GET",
+            headers: { accept: "application/json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return `unreachable (${causeText(err)})`;
+    }
+    if (res.status >= 300 && res.status < 400) {
+        return `redirects to ${res.headers.get("location") ?? "somewhere else"} — use the final address`;
+    }
+    const type = (res.headers.get("content-type") ?? "").toLowerCase();
+    if (!res.ok) {
+        return `GET /health answered HTTP ${res.status}${type.includes("html") ? " with a web page" : ""}`;
+    }
+    if (!type.includes("json")) {
+        const what = type.includes("html") ? "a web page" : type ? `'${type}'` : "no content type";
+        return `GET /health answered ${what} instead of JSON — that is a website, not the BaseIn API`;
+    }
+    return undefined;
+}
 function prompt(question) {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     return new Promise((resolve) => {
@@ -215,7 +291,13 @@ async function postJson(url, body) {
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(`HTTP ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
+        const isHtml = (res.headers.get("content-type") ?? "").includes("html") || /^\s*<(!doctype|html)/i.test(text);
+        const detail = isHtml
+            ? " — the answer was a web page, not JSON: this URL is a website, not the BaseIn API"
+            : text
+                ? ` — ${text.length > 300 ? `${text.slice(0, 300)}…` : text}`
+                : "";
+        throw new Error(`HTTP ${res.status} ${res.statusText}${detail}`);
     }
     return (await res.json());
 }
@@ -258,13 +340,222 @@ export async function authenticate(opts) {
             return refreshed;
         }
     }
-    if (opts?.nonInteractive || !process.stdin.isTTY) {
-        logLine("auth.no_session", {
-            why: "no valid session and no terminal to log in on — run `bir login`",
+    // No session, and this function does not make one. Signing in is a browser
+    // round trip that can take minutes; a proxy or control server blocking on it
+    // would hang the host instead of degrading to not-recording.
+    logLine("auth.no_session", {
+        why: "no valid session — run `bir login`",
+    });
+    return undefined;
+}
+// ── Device authorization grant (RFC 8628) ──────────────────────────────────
+/**
+ * The service has no device endpoints — it predates browser sign-in.
+ *
+ * Thrown so `bir login` can fall back to the password flow rather than leaving
+ * someone stranded on a runner that is newer than the service it talks to.
+ */
+export class DeviceFlowUnsupported extends Error {
+    constructor() {
+        super("this BaseIn service does not offer browser sign-in");
+        this.name = "DeviceFlowUnsupported";
+    }
+}
+/**
+ * Start a sign-in. Returns the codes; the caller shows one and polls with the
+ * other.
+ *
+ * `clientName`/`clientVersion` are shown on the approval page so the person can
+ * tell their own `bir login` from somebody else's — the one defence a device
+ * flow has against being talked into approving a stranger's code.
+ */
+export async function startDeviceCode(authUrl, client, fetchImpl = fetch) {
+    const res = await fetchImpl(`${authUrl}/auth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ clientName: client.name, clientVersion: client.version }),
+    });
+    // A service without the endpoint 404s. Anything else is a real failure.
+    if (res.status === 404)
+        throw new DeviceFlowUnsupported();
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const isHtml = (res.headers.get("content-type") ?? "").includes("html") || /^\s*<(!doctype|html)/i.test(text);
+        throw new Error(`HTTP ${res.status}${isHtml
+            ? " — the answer was a web page, not JSON: this URL is a website, not the BaseIn API"
+            : text
+                ? ` — ${text.slice(0, 300)}`
+                : ""}`);
+    }
+    return (await res.json());
+}
+/** The user gave up, or the code died before anyone approved it. */
+export class DeviceFlowAborted extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "DeviceFlowAborted";
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll until the sign-in is approved, refused, or dies.
+ *
+ * RFC 8628 §3.5's loop, including the part people skip: `slow_down` is not an
+ * error, it is the server asking for a longer gap, and the interval must
+ * *stay* longer afterwards. Ignoring it turns a slow client into a blocked one.
+ */
+export async function pollDeviceToken(authUrl, deviceCode, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    const deadline = now() + opts.expiresIn * 1000;
+    let interval = opts.interval;
+    for (;;) {
+        if (opts.signal?.aborted) {
+            throw new DeviceFlowAborted("sign-in cancelled", "cancelled");
+        }
+        if (now() >= deadline) {
+            throw new DeviceFlowAborted("the code expired before it was approved — run `bir login` again", "timeout");
+        }
+        await sleep(interval * 1000);
+        const res = await fetchImpl(`${authUrl}/auth/device/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ deviceCode }),
+        });
+        if (res.ok)
+            return (await res.json());
+        const body = (await res.json().catch(() => ({})));
+        switch (body.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                // Adopt the server's number when it sends one; otherwise back off the
+                // way the RFC suggests. Either way the wider gap persists.
+                interval = typeof body.interval === "number" ? body.interval : interval + 5;
+                continue;
+            case "access_denied":
+                throw new DeviceFlowAborted("the sign-in was refused in the browser", "access_denied");
+            case "expired_token":
+                throw new DeviceFlowAborted("the code expired before it was approved — run `bir login` again", "expired_token");
+            default:
+                throw new Error(`sign-in failed: ${body.error ?? `HTTP ${res.status}`}`);
+        }
+    }
+}
+/**
+ * Open a URL in the user's browser. Best effort, and never fatal.
+ *
+ * No dependency and no shell: this package ships zero runtime dependencies, and
+ * passing a URL through a shell is how a URL becomes a command. The link is
+ * printed either way, so a failure here costs nothing.
+ */
+export function openBrowser(url) {
+    try {
+        const [command, args] = process.platform === "win32"
+            ? // The empty string is `start`'s title argument. Without it, a quoted
+                // URL is taken *as* the title and nothing opens.
+                ["cmd", ["/c", "start", "", url]]
+            : process.platform === "darwin"
+                ? ["open", [url]]
+                : ["xdg-open", [url]];
+        const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+        child.on("error", () => {
+            /* no browser here; the printed link is the fallback */
         });
+        child.unref();
+    }
+    catch {
+        /* see above */
+    }
+}
+/**
+ * Should we try to open a browser at all?
+ *
+ * Over SSH the browser would open on the wrong machine, and with no terminal
+ * there is nobody watching. In both cases the link still gets printed — it can
+ * be opened on a phone, which is the point of this grant.
+ */
+function shouldOpenBrowser() {
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY)
+        return false;
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * Sign in through the browser and cache the session.
+ *
+ * Everything a person sees goes to stderr: `bir login`'s stdout is one line
+ * that a script may read, and the code block is not it.
+ */
+export async function deviceLogin(authUrl, opts = {}) {
+    const write = opts.write ?? ((text) => process.stderr.write(text));
+    const grant = await startDeviceCode(authUrl, { name: clientName(), version: packageVersion() }, opts.fetchImpl);
+    const link = grant.verificationUriComplete ?? grant.verificationUri;
+    write(`\n[bir] Sign in to ${authUrl}\n\n`);
+    write(`  Open   ${link}\n`);
+    write(`  Code   ${grant.userCode}\n\n`);
+    const wantsBrowser = opts.openBrowser ?? shouldOpenBrowser();
+    if (wantsBrowser) {
+        write("  Opening your browser…\n");
+        openBrowser(link);
+    }
+    else {
+        write("  Open that link on any device — a phone is fine.\n");
+    }
+    write("  Waiting for approval…  (Ctrl-C to cancel)\n\n");
+    logLine("auth.device_started", { url: authUrl, expiresIn: grant.expiresIn });
+    const res = await pollDeviceToken(authUrl, grant.deviceCode, {
+        interval: grant.interval,
+        expiresIn: grant.expiresIn,
+        fetchImpl: opts.fetchImpl,
+        sleep: opts.sleep,
+        signal: opts.signal,
+    });
+    const session = toSession(res);
+    saveCredentials(session);
+    return session;
+}
+/**
+ * A name for this machine, shown on the approval page.
+ *
+ * This is the string someone reads to decide whether the request is theirs, so
+ * it names the tool and the host. Never fatal: an unnamed client still works,
+ * it just tells the approver less.
+ */
+function clientName() {
+    try {
+        return `bir on ${hostname()}`;
+    }
+    catch {
+        return "bir";
+    }
+}
+// ── The password flow, on its way out ──────────────────────────────────────
+/**
+ * Sign in with an email and a password.
+ *
+ * DEPRECATED, and kept for exactly two cases: `bir login --password`, and a
+ * runner talking to a service that predates the device endpoints. Both go in
+ * the release after this one, and this function goes with them.
+ *
+ * It cannot work at all for an account created through Google — there is no
+ * password on it to send — which is the main reason sign-in moved.
+ */
+export async function legacyPasswordLogin(authUrl) {
+    if (!process.stdin.isTTY) {
+        logLine("auth.no_session", { why: "no terminal to read a password on" });
+        return undefined;
+    }
+    // Never send a password to something that is not the service. The website
+    // answers 405 *after* the credentials have been posted to it; check first.
+    const problem = await describeAuthService(authUrl);
+    if (problem) {
+        logLine("auth.not_a_service", { url: authUrl, problem, why: AUTH_URL_HINT });
         return undefined;
     }
-    process.stderr.write(`[bir] Sign in to ${authUrl}\n`);
+    process.stderr.write(`[bir] Sign in to ${authUrl}  (BIR_AUTH_URL)\n`);
     const email = await prompt("Email: ");
     const password = await promptPassword("Password: ");
     if (!email || !password) {
@@ -277,8 +568,35 @@ export async function authenticate(opts) {
         return session;
     }
     catch (err) {
-        logLine("auth.login_failed", { error: errText(err) });
+        logLine("auth.login_failed", { url: `${authUrl}/auth/login`, error: errText(err) });
         return undefined;
     }
 }
+/**
+ * Sign out: revoke the refresh token server-side, then forget it locally.
+ *
+ * Deleting the file alone left the token live for its full 30 days, which made
+ * `bir logout` a tidy-up rather than a revocation. The endpoint is idempotent
+ * and its failure is not worth blocking on — the local half must happen either
+ * way, or "logged out" would be a lie on a machine with no network.
+ */
+export async function logout(authUrl) {
+    const cached = loadCredentials();
+    if (authUrl && cached?.refreshToken) {
+        try {
+            await fetch(`${authUrl}/auth/logout`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ refreshToken: cached.refreshToken }),
+            });
+        }
+        catch (err) {
+            logLine("auth.logout_remote_failed", {
+                error: errText(err),
+                why: "the local credentials are cleared regardless",
+            });
+        }
+    }
+    clearCredentials();
+}
 //# sourceMappingURL=client.js.map

package/dist/bin/bir.js

@@ -28,7 +28,7 @@ import { isScenarioServer, isWrapped, PACKAGE_NAME, readSidecar, scenarioEntry,
 import { isRemote, resolveServers } from "../config/resolve.js";
 import { buildHooksBlock, claudeCodePaths, fileForScope, installHooks, readTextOrNull, setServerEntry, sha256, uninstallHooks, } from "../config/adapters/claude-code.js";
 import { readGenericServers, setGenericServerEntry } from "../config/adapters/generic.js";
-import { clearCredentials, authenticate, resolveAuthUrl, normalizeAuthUrl } from "../auth/client.js";
+import { AUTH_URL_HINT, DeviceFlowAborted, DeviceFlowUnsupported, authenticate, deviceLogin, describeAuthService, legacyPasswordLogin, logout, normalizeAuthUrl, resolveAuthUrl, } from "../auth/client.js";
 import { DEFAULT_CONTROL_PORT } from "../control/server.js";
 import { errText } from "../util/log.js";
 import { packageVersion } from "../util/version.js";
@@ -45,8 +45,8 @@ Commands:
   status      what is installed for this directory
   doctor      is it actually working right now?
   wrap        print a proxied entry for one server (any MCP client)
-  login       sign in to the BaseIn service
-  logout      forget the cached credentials
+  login       sign in to the BaseIn service (opens your browser)
+  logout      revoke this machine's session and forget it
 
   scenario list                     recorded runs and their calculated scenarios
   scenario show <runId>             a run's scenario: intent, params, steps
@@ -65,7 +65,9 @@ Options:
   --replay          install/remove the scenario server, enabling calculated replay
   --port <n>        control-server port to write into the hook URLs (default ${DEFAULT_CONTROL_PORT})
   --json            machine-readable output for status / doctor
-  --dry             replay against recorded outputs only; run no real tools`);
+  --dry             replay against recorded outputs only; run no real tools
+  --no-browser      login: print the link and code, open nothing (SSH, headless)
+  --password        login: use the old email/password prompt (deprecated)`);
     process.exit(code);
 }
 function parseArgs(argv) {
@@ -83,6 +85,7 @@ function parseArgs(argv) {
         positionals: [],
         dry: false,
         force: false,
+        password: false,
     };
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -106,6 +109,12 @@ function parseArgs(argv) {
             case "--force":
                 args.force = true;
                 break;
+            case "--password":
+                args.password = true;
+                break;
+            case "--no-browser":
+                args.browser = false;
+                break;
             case "--config":
                 args.configPath = argv[++i];
                 break;
@@ -538,12 +547,31 @@ async function doctor(args) {
         notes.push("could not verify recording: no control server to ask, and BIR_AUTH_URL is " +
             "unset in this shell (which is not where the proxies read it from)");
     }
+    // WHAT *THIS* SHELL WOULD TALK TO. `bir login` and `bir scenario` run here,
+    // so this shell's BIR_AUTH_URL is evidence about them, if not about the
+    // recorder. The one mistake worth catching is a URL that is a website rather
+    // than the API: it answers `GET /health` with a page, so nothing else notices
+    // until a password has been posted to it and it says `405`.
+    const shellAuthUrl = resolveAuthUrl();
+    const shellAuthProblem = shellAuthUrl ? await describeAuthService(shellAuthUrl) : undefined;
+    if (shellAuthProblem) {
+        problems.push(`BIR_AUTH_URL in this shell (${shellAuthUrl}) is not a BaseIn service: ${shellAuthProblem}. ` +
+            `\`bir login\` and \`bir scenario\` here will fail — ${AUTH_URL_HINT}`);
+    }
     const sidecar = readSidecar();
     if (sidecar.controlPort && discovery && !discovery.url.endsWith(`:${sidecar.controlPort}`)) {
         problems.push(`hooks were installed for port ${sidecar.controlPort} but the control server is on ${discovery.url}`);
     }
     if (args.json) {
-        out(JSON.stringify({ ok: problems.length === 0, problems, notes, health, wrapped: wantWrapped }, null, 2));
+        out(JSON.stringify({
+            ok: problems.length === 0,
+            problems,
+            notes,
+            health,
+            wrapped: wantWrapped,
+            shellAuthUrl: shellAuthUrl || null,
+            shellAuthProblem: shellAuthProblem ?? null,
+        }, null, 2));
         return problems.length === 0 ? 0 : 1;
     }
     // Replay first, and loudly. It auto-approves tool calls in the session and
@@ -567,6 +595,9 @@ async function doctor(args) {
     out(`Wrapped in config : ${wantWrapped.join(", ") || "(none)"}`);
     out(`Registered proxies: ${[...registered].join(", ") || "(none)"}`);
     out(`Control server    : ${discovery?.url ?? "not running"}`);
+    out(`BaseIn (shell)    : ${shellAuthUrl
+        ? `${shellAuthUrl}${shellAuthProblem ? " — NOT a BaseIn service, see below" : " (answers /health)"}`
+        : "(BIR_AUTH_URL not set in this shell)"}`);
     out(`Recording tier    : ${discovery && health ? "bound (Tier 1)" : "standalone (Tier 2)"}`);
     out(`Recording         : ${health ? (health.recording === false ? "no — see below" : "yes") : "unknown (no control server to ask)"}`);
     if (health?.lossy)
@@ -853,16 +884,63 @@ async function main() {
         case "replay":
             return replayCommand(args);
         case "login": {
-            const session = await authenticate();
+            // Settle the URL the way every other command does, then refuse to go on
+            // when what is there is not the service. "Signed in" must mean the service
+            // at BIR_AUTH_URL issued this session — not that a cached token exists for
+            // some other address.
+            const configured = resolveAuthUrl();
+            if (!configured) {
+                process.stderr.write("[bir] BIR_AUTH_URL is not set — there is nothing to sign in to.\n");
+                process.stderr.write(`[bir] ${AUTH_URL_HINT}\n`);
+                return 1;
+            }
+            const baseUrl = await normalizeAuthUrl(configured);
+            const problem = await describeAuthService(baseUrl);
+            if (problem) {
+                process.stderr.write(`[bir] ${baseUrl} is not a BaseIn service: ${problem}\n`);
+                process.stderr.write(`[bir] ${AUTH_URL_HINT}\n`);
+                return 1;
+            }
+            let session;
+            if (args.password) {
+                process.stderr.write("[bir] --password is deprecated and will be removed in the next release. " +
+                    "Browser sign-in works for every account, including Google-only ones.\n");
+                session = await legacyPasswordLogin(baseUrl);
+            }
+            else {
+                try {
+                    session = await deviceLogin(baseUrl, { openBrowser: args.browser });
+                }
+                catch (err) {
+                    if (err instanceof DeviceFlowUnsupported) {
+                        // A runner newer than its service. Falling back beats stranding
+                        // someone on an install that used to work.
+                        process.stderr.write("[bir] this service does not offer browser sign-in yet; " +
+                            "falling back to email and password.\n");
+                        session = await legacyPasswordLogin(baseUrl);
+                    }
+                    else if (err instanceof DeviceFlowAborted) {
+                        process.stderr.write(`[bir] ${err.message}\n`);
+                        return 1;
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
             if (!session)
                 return 1;
-            out(`Signed in as ${session.user.email}.`);
+            out(`Signed in to ${baseUrl} as ${session.user.email}.`);
             return 0;
         }
-        case "logout":
-            clearCredentials();
+        case "logout": {
+            // Revoke server-side before forgetting locally, so a stolen credentials
+            // file is dead rather than merely absent from this machine.
+            const configured = resolveAuthUrl();
+            await logout(configured ? await normalizeAuthUrl(configured) : undefined);
             out("Logged out — cached credentials cleared.");
             return 0;
+        }
         default:
             usage(2);
     }

package/dist/proxy/session.js

@@ -214,10 +214,11 @@ export class ProxySession {
             logLine("recorder.disabled", { why: "BIR_AUTH_URL is not set" });
             return new NullRecorder();
         }
-        // Non-interactive: a proxy runs inside the host's process tree with its stdio
-        // bound to the JSON-RPC stream. There is nowhere to prompt, and blocking on
-        // one would hang the host's server startup.
-        const session = await authenticate({ authUrl: baseUrl, nonInteractive: true });
+        // A proxy runs inside the host's process tree with its stdio bound to the
+        // JSON-RPC stream: there is nowhere to prompt, and blocking on one would
+        // hang the host's server startup. `authenticate` never interacts — signing
+        // in lives in `bir login` alone — so that is guaranteed here, not requested.
+        const session = await authenticate({ authUrl: baseUrl });
         if (!session) {
             logLine("recorder.disabled", { why: "no BaseIn session — run `bir login`" });
             return new NullRecorder();

package/docs/calculatedReplayGuide.md

@@ -44,7 +44,7 @@ honest ceiling rather than a bug.
 export BIR_AUTH_URL=https://your-basein-service
 npm install && npm run build
 node dist/bin/bir.js install        # or `bir install` once linked/published
-bir login
+bir login                           # prints a link and a code; approve in the browser
 bir-hooks                           # leave running in its own terminal
 ```
 

package/docs/installRun.md

@@ -189,7 +189,7 @@ runs":
 | Scope | How often | What it does |
 |---|---|---|
 | **machine** | once | Node ≥ 20, and the package installed globally |
-| **account** | once per user | `BIR_AUTH_URL`, then `bir login` → `~/.baseinstrunner/credentials.json` (0600) |
+| **account** | once per user | `BIR_AUTH_URL`, then `bir login` (approved in a browser) → `~/.baseinstrunner/credentials.json` (0600) |
 | **project** | once per repo | `bir install --global` rewrites that project's MCP entries and wires the hooks |
 | **session** | while recording | `bir-hooks` running, discovered by `sha256(normalised cwd)` |
 
@@ -288,22 +288,35 @@ so the tarball has to be carried to the runner by whatever means you already use
 
 ---
 
-## 7. Headless authentication — still a stopgap
+## 7. Headless authentication
 
-`bir login` prompts for email and password on a TTY and caches
+`bir login` signs in through the browser — the OAuth 2.0 device grant (RFC 8628,
+[loginWeb.md](loginWeb.md)) — and caches
 `{accessToken, refreshToken, accessExpiresAt, user}` at
-`~/.baseinstrunner/credentials.json`, mode 0600. For a fleet, in order of
-preference:
-
-1. **Pre-seed the credentials file.** Log in once as a dedicated service account,
-   copy `credentials.json` to each machine at 0600. The refresh token keeps it
-   alive and nothing prompts. Works today — but it is a shared long-lived secret,
-   so never a person's account.
-2. **`BIR_NO_AUTH` / `BIR_AUTH_DISABLE=1`** for runners that should record
-   nothing. Everything else still works.
-3. **Ask the service for a non-interactive grant** — client credentials, or a
-   long-lived runner token read from an env var. This is the right answer for a
-   fleet, and it is a service-side change. Worth raising before the fleet grows.
+`~/.baseinstrunner/credentials.json`, mode 0600.
+
+**For a machine with a person attached, headless is no longer a problem.** The
+runner prints a link and a short code and waits; the link opens on *any* device,
+so a box with no browser, no display, or only an SSH session is signed in from a
+phone. Nothing is typed into the terminal, so nothing lands in a shell history or
+a CI transcript. `bir login --no-browser` skips even trying to open one, which is
+the right flag in a provisioning script (it is also the default over SSH).
+
+For machines with **no person attached**, in order of preference:
+
+1. **A service account, signed in once.** Approve the device code for a dedicated
+   account, then copy `credentials.json` to each machine at 0600. The rotating
+   refresh token keeps it alive and nothing ever prompts. It is still a shared
+   long-lived secret, so never a person's account.
+2. **`BIR_AUTH_DISABLE=1`** for runners that should record nothing. Everything
+   else still works.
+3. **Ask the service for a non-interactive grant** — a long-lived runner token,
+   created in the console and read from an env var. This remains the right answer
+   for a large fleet and is still a service-side change; the device grant makes
+   it less urgent, not unnecessary.
+
+`bir logout` now revokes the session server-side before clearing the file, so
+decommissioning a runner ends its access rather than merely tidying the disk.
 
 `BIR_HOME` relocates all of this if state belongs somewhere other than
 `~/.baseinstrunner`.