@basein/runner 0.1.1 → 0.2.0

package/README.md

@@ -51,11 +51,18 @@ byte-for-byte.
 
 ```bash
 export BIR_AUTH_URL=https://your-basein-service   # required to record anything
-bir login                                        # once
+bir login                                        # once; approve it in the browser
 bir-hooks                                        # leave running; Ctrl-C to stop
 claude                                           # your session, now recorded
 ```
 
+`bir login` prints a link and a short code and waits for you to approve it in
+the browser — the OAuth device grant, the same shape `gh auth login` uses. It
+never handles a password, so it works for accounts that only sign in with
+Google, and the link can be opened on any device, which is what makes it usable
+on a headless runner. `--no-browser` prints the link without opening one;
+`--password` is the deprecated email-and-password prompt, removed next release.
+
 Check it:
 
 ```bash

package/dist/auth/client.d.ts

@@ -1,21 +1,35 @@
 /**
- * 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).
@@ -36,8 +50,13 @@ export interface AuthSession {
 export interface AuthenticateOptions {
     /** Base URL of the auth service. Defaults to BIR_AUTH_URL. */
     authUrl?: string;
-    /** Never prompt: fail (return undefined) if no valid/refreshable session exists. */
-    nonInteractive?: boolean;
+}
+interface AuthResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Access token lifetime in seconds. */
+    expiresIn: number;
+    user: AuthUser;
 }
 /**
  * Where the cached session lives.
@@ -105,4 +124,101 @@ export declare function describeAuthService(baseUrl: string, fetchImpl?: typeof
  * obtained. Callers degrade to not-recording rather than failing the session.
  */
 export declare function authenticate(opts?: AuthenticateOptions): Promise<AuthSession | undefined>;
+/**
+ * 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 declare class DeviceFlowUnsupported extends Error {
+    constructor();
+}
+/** The CLI's view of a started device authorization. */
+export interface DeviceCodeGrant {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresIn: number;
+    interval: number;
+}
+/**
+ * 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 declare function startDeviceCode(authUrl: string, client: {
+    name?: string;
+    version?: string;
+}, fetchImpl?: typeof fetch): Promise<DeviceCodeGrant>;
+/** The user gave up, or the code died before anyone approved it. */
+export declare class DeviceFlowAborted extends Error {
+    readonly reason: "access_denied" | "expired_token" | "timeout" | "cancelled";
+    constructor(message: string, reason: "access_denied" | "expired_token" | "timeout" | "cancelled");
+}
+export interface PollOptions {
+    interval: number;
+    expiresIn: number;
+    fetchImpl?: typeof fetch;
+    /** Injected so tests run in milliseconds rather than minutes. */
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    now?: () => number;
+}
+/**
+ * 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 declare function pollDeviceToken(authUrl: string, deviceCode: string, opts: PollOptions): Promise<AuthResponse>;
+/**
+ * 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 declare function openBrowser(url: string): void;
+export interface DeviceLoginOptions {
+    /** `--no-browser`, or a machine where opening one is wrong. */
+    openBrowser?: boolean;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    /** Where the human-readable lines go. stderr, so stdout stays parseable. */
+    write?: (text: string) => void;
+}
+/**
+ * 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 declare function deviceLogin(authUrl: string, opts?: DeviceLoginOptions): Promise<AuthSession | undefined>;
+/**
+ * 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 declare function legacyPasswordLogin(authUrl: string): Promise<AuthSession | 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 declare function logout(authUrl?: string): Promise<void>;
+export {};
 //# sourceMappingURL=client.d.ts.map

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.
  *
@@ -323,10 +340,212 @@ 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
@@ -353,4 +572,31 @@ export async function authenticate(opts) {
         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 { AUTH_URL_HINT, authenticate, clearCredentials, describeAuthService, normalizeAuthUrl, resolveAuthUrl, } 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;
@@ -875,30 +884,63 @@ async function main() {
         case "replay":
             return replayCommand(args);
         case "login": {
-            // Settle the URL the way every other command does, then refuse to ask for
-            // a password when what is there is not the service. "Signed in" must mean
-            // the service at BIR_AUTH_URL accepted these credentials — not that a
-            // cached token exists for some other address.
+            // 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();
-            const baseUrl = configured ? await normalizeAuthUrl(configured) : "";
-            if (baseUrl) {
-                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;
+            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;
+                    }
                 }
             }
-            const session = await authenticate(baseUrl ? { authUrl: baseUrl } : undefined);
             if (!session)
                 return 1;
             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
 ```