bikeshed-now 0.5.0 → 0.9.0

package/README.md

@@ -10,13 +10,23 @@ works the same, with your address in place of `https://bikeshed.now`.
 
 ```bash
 npm i -g bikeshed-now
-bikeshed login            # asks for the deployment and a token
+bikeshed login            # signs you in through your browser
 ```
 
-Create a token at [bikeshed.now/account](https://bikeshed.now/account) — choose
-**Command line**. It is shown once. `BIKESHED_ORIGIN` and `BIKESHED_TOKEN` work
-instead of `login` where an interactive command cannot run — a CI job, or an
-agent.
+`login` opens your browser at the deployment. Sign in if you need to, click
+Approve, and the terminal saves a token that only you can read. It prints the
+link as well, for when no browser opens. Pass `--origin <url>` for your own
+deployment, or `--no-browser` to open the link yourself. An agent can run
+`npx -y bikeshed-now login` for you: you approve in your browser, and the token
+never appears in its output.
+
+The browser has to be on the same computer as the terminal, because it hands
+the sign-in back to a port on `127.0.0.1`. Over SSH, or against a deployment
+too old to offer browser sign-in, create a token at
+[bikeshed.now/account](https://bikeshed.now/account), choose **Command line**,
+and run `bikeshed login --paste`. The token is shown once. In CI, set
+`BIKESHED_ORIGIN` and `BIKESHED_TOKEN` instead of running `login` at all; they
+outrank whatever `login` saved.
 
 ## The loop
 
@@ -27,9 +37,17 @@ bikeshed publish proposal.md --title "Storage migration"
 # Somebody highlights a sentence and says what is wrong with it.
 bikeshed comments storage-migration
 
-# Fix that sentence, publish the revision, and say what you changed.
-bikeshed update storage-migration proposal.md
+# Fix that sentence, say what you changed in its thread, then publish the
+# revision. Reply first: a thread belongs to the version it was written on.
 bikeshed reply storage-migration <thread> "Rewritten to describe the dual-write period."
+bikeshed update storage-migration proposal.md
+
+# Given "Can suggest" rather than "Can edit"? Propose the change instead, for a
+# person to accept or reject.
+bikeshed suggest storage-migration "a single weekend" --with "two weekends"
+
+# Something nobody has raised yet? Start a thread on the passage it is about.
+bikeshed comment storage-migration "a single weekend" --body "Is the dual-write fortnight in this?"
 ```
 
 Publishing identical bytes is a no-op: the bundle is hashed, and a matching hash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikeshed-now",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",
@@ -26,7 +26,7 @@
     "bikeshed": "src/index.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "files": [
     "src",

package/src/client.mjs

@@ -4,7 +4,7 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 
-export const CLIENT_NAME = "bikeshed-cli/0.5.0";
+export const CLIENT_NAME = "bikeshed-cli/0.9.0";
 
 /**
  * Three surfaces, and the split is deliberate rather than untidy.
@@ -165,6 +165,65 @@ export async function fetchSkill(origin, skill) {
   return res.text();
 }
 
+/**
+ * Text a server chose, made safe to print in a terminal: control characters
+ * (an escape sequence can rewrite what a terminal shows) go, and it is cut to
+ * a line's worth.
+ */
+export function printable(text, max = 200) {
+  const clean = String(text ?? "").replace(/[\p{Cc}\p{Cf}]/gu, " ").trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/** The only thing the token endpoint may hand the CLI: a personal access token. */
+const ACCESS_TOKEN_RE = /^bsk_[0-9a-f]{32}\.[A-Za-z0-9_-]{20,64}$/;
+
+/**
+ * Trade a browser sign-in's code for a token (SPEC §23).
+ *
+ * Form-encoded, as OAuth defines the token request. Redirects are refused: a
+ * token endpoint that moves is not one to send a code and its verifier after.
+ * Whatever comes back has to be shaped like a personal access token before it
+ * is stored, because it is about to be saved as one and sent on every call.
+ */
+export async function exchangeCode(tokenEndpoint, { code, verifier, redirectUri, clientId, resource }) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: verifier,
+    resource,
+  });
+  let res;
+  try {
+    res = await fetch(tokenEndpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body,
+      redirect: "error",
+    });
+  } catch (e) {
+    throw new CliError(`could not finish signing in: ${e.cause?.code ?? e.message}. Nothing was saved.`);
+  }
+  const answer = await res.json().catch(() => null);
+
+  if (!res.ok) {
+    const error = typeof answer?.error === "string" ? answer.error : `HTTP ${res.status}`;
+    const detail = answer?.error_description ? `: ${printable(answer.error_description)}` : "";
+    const advice =
+      error === "invalid_grant"
+        ? "The sign-in code expired or was already used."
+        : "The deployment refused the sign-in.";
+    throw new CliError(`${advice} Nothing was saved; run \`bikeshed login\` again. (${printable(error, 60)}${detail})`);
+  }
+  const token = answer?.access_token;
+  if (typeof token !== "string" || !ACCESS_TOKEN_RE.test(token)) {
+    throw new CliError("The deployment answered with something that is not a Bikeshed token. Nothing was saved.");
+  }
+  return token;
+}
+
 /** Check that a token works, and say who it belongs to. */
 export async function whoami(origin, token) {
   // list_documents is the cheapest authenticated call, and a token that can

package/src/index.mjs

@@ -11,12 +11,26 @@ import { CONFIG_PATH, readConfig, resolveAuth, writeConfig } from "./config.mjs"
 import {
   CliError,
   callTool,
+  exchangeCode,
   fetchSkill,
   fetchSource,
   listSkills,
+  printable,
   uploadFile,
   whoami,
 } from "./client.mjs";
+import {
+  CLI_CLIENT_ID,
+  LOGIN_TIMEOUT_MS,
+  authorizeUrl,
+  canOpenBrowser,
+  createPkce,
+  createState,
+  deviceName,
+  discover,
+  listenForCallback,
+  openBrowser,
+} from "./login.mjs";
 
 /**
  * This is the END-USER tool, and it is deliberately not the same thing as the
@@ -35,7 +49,7 @@ import {
 
 const USAGE = `bikeshed — publish and revise documents
 
-  bikeshed login                       store a personal access token
+  bikeshed login                       sign in through your browser (--paste for a token)
   bikeshed list                        documents you can read
   bikeshed publish <file>              create a new document
   bikeshed update <id> <file>          publish a new version
@@ -43,7 +57,13 @@ const USAGE = `bikeshed — publish and revise documents
   bikeshed lineage <id>                what it was forked from; for its owner, its forks
   bikeshed get <id>                    print a document's source
   bikeshed comments <id>               unresolved feedback, with its anchored text
+  bikeshed comment <id> <text> --body <comment>
+                                       start a thread on a passage
   bikeshed reply <id> <thread> <text>  reply in a thread
+  bikeshed suggest <id> <text> --with <new text>
+                                       propose new text for a passage, for a
+                                       person to accept or reject (--delete to
+                                       propose removing it)
   bikeshed open <id>                   open it in a browser
 
   Where a command takes <id> it also takes the link you were sent. An unlisted
@@ -82,7 +102,14 @@ Options
   --limit <n>            with list: rows per page (default 20, max 50)
   --cursor <id>          with list: the page after the one that printed it
   --all                  with list: every page; with comments: resolved too
+  --with <text>          with suggest: what the passage should say instead
+  --delete               with suggest: propose deleting the passage
+  --note <text>          with suggest: why, for whoever decides
+  --prefix <text>        with suggest: words just before a passage that repeats
+  --suffix <text>        with suggest: words just after it
   --watch                with publish/update: republish on every save
+  --paste                with login: paste a token made at /account instead
+  --no-browser           with login: print the sign-in link without opening it
   --origin <url>         the deployment (default: the one you logged in to)
   --token <token>        override the stored token
   --help                 this
@@ -137,7 +164,140 @@ function isArchive(path, bytes) {
 
 // --- Commands --------------------------------------------------------------
 
+/**
+ * Sign in. Through the browser by default, by pasting a token with --paste.
+ *
+ * The browser flow needs no terminal on stdin, on purpose: an agent's shell
+ * has none, and an agent running `npx -y bikeshed-now login` on a person's
+ * behalf is the case it exists for. The person approves in their own browser;
+ * the agent never sees the token, and neither does anybody reading its
+ * output. So the address goes to stderr, stdout stays parseable for --json,
+ * and the token is never printed.
+ */
 async function login(flags) {
+  if (flags.paste) return pasteLogin(flags);
+  // A job runner has no browser and no person to approve. Waiting five minutes
+  // to say so would be the slowest possible way to fail.
+  if (isCi(process.env.CI) && !flags["no-browser"]) {
+    fail("In CI, set BIKESHED_TOKEN and BIKESHED_ORIGIN.");
+  }
+  return browserLogin(flags);
+}
+
+function isCi(value) {
+  return Boolean(value) && value !== "0" && value.toLowerCase() !== "false";
+}
+
+async function browserLogin(flags) {
+  const interactive = Boolean(process.stdin.isTTY);
+  let where = resolveAuth(flags).origin;
+  if (interactive && !flags.origin) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      where = (await rl.question(`Deployment [${where}]: `)).trim() || where;
+    } finally {
+      rl.close();
+    }
+  }
+  try {
+    const url = new URL(where);
+    if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error();
+    where = url.origin;
+  } catch {
+    fail(`not a deployment address: ${where} (try https://bikeshed.now)`);
+  }
+
+  const meta = await discover(where);
+  if (!meta) {
+    // A deployment from before browser sign-in. A person at a terminal can
+    // still paste; anything else is told how, rather than left at a prompt
+    // nobody will answer.
+    if (interactive) {
+      console.error(`${where} predates browser sign-in, so this will ask for a token instead.\n`);
+      return pasteLogin({ ...flags, origin: where });
+    }
+    fail(`${where} predates browser sign-in. Create a token at ${where}/account and run \`bikeshed login --paste\`.`);
+  }
+
+  const { verifier, challenge } = createPkce();
+  const state = createState();
+  const timeoutMs = Number(process.env.BIKESHED_LOGIN_TIMEOUT_MS) || LOGIN_TIMEOUT_MS;
+  const callback = await listenForCallback({ state, issuer: meta.issuer, timeoutMs });
+  const resource = `${where}/mcp`;
+  const url = authorizeUrl(meta.authorization_endpoint, {
+    clientId: CLI_CLIENT_ID,
+    redirectUri: callback.redirectUri,
+    challenge,
+    state,
+    resource,
+    device: deviceName(),
+  });
+
+  const onInterrupt = () => {
+    callback.close();
+    console.error("\nCancelled. Nothing was saved.");
+    process.exit(130);
+  };
+  process.once("SIGINT", onInterrupt);
+
+  let answer;
+  try {
+    const here = canOpenBrowser();
+    const opening = !flags["no-browser"] && here && openBrowser(url);
+    console.error(
+      opening
+        ? `Opening your browser to sign in to ${where}. If it does not open, visit:`
+        : `To sign in to ${where}, open this in your browser:`,
+    );
+    console.error(`\n  ${url}\n`);
+    if (!flags["no-browser"] && !here) {
+      // The redirect comes back to 127.0.0.1 on THIS machine, which a browser
+      // on another one cannot reach.
+      console.error("If your browser is on another computer, it cannot reach back here: use `bikeshed login --paste` instead.");
+    }
+    console.error("Waiting for you to approve… (Ctrl-C to cancel)");
+    answer = await callback.result;
+  } finally {
+    process.off("SIGINT", onInterrupt);
+  }
+
+  if (answer.error) {
+    if (answer.error === "access_denied") fail("You chose not to connect. Nothing was saved.");
+    fail(`Sign-in did not finish: ${printable(answer.description ?? answer.error)}. Nothing was saved.`);
+  }
+
+  const token = await exchangeCode(meta.token_endpoint, {
+    code: answer.code,
+    verifier,
+    redirectUri: callback.redirectUri,
+    clientId: CLI_CLIENT_ID,
+    resource,
+  });
+  // Checked before it is stored, the same as a pasted one.
+  await whoami(where, token);
+  writeConfig({ ...readConfig(), origin: where, token });
+
+  // The environment outranks the file (resolveAuth), so a variable left over
+  // from an earlier session would quietly keep being used instead.
+  // A BIKESHED_ORIGIN naming this same deployment changes nothing.
+  const shadowing = [];
+  if (process.env.BIKESHED_TOKEN) shadowing.push("BIKESHED_TOKEN");
+  if (process.env.BIKESHED_ORIGIN && process.env.BIKESHED_ORIGIN.replace(/\/+$/, "") !== where) {
+    shadowing.push("BIKESHED_ORIGIN");
+  }
+  if (shadowing.length === 1) {
+    console.error(`${shadowing[0]} is set in this shell, and it outranks what was just saved. Unset it to use this sign-in.`);
+  } else if (shadowing.length === 2) {
+    console.error("BIKESHED_TOKEN and BIKESHED_ORIGIN are set in this shell, and they outrank what was just saved. Unset them to use this sign-in.");
+  }
+
+  out(flags.json, { origin: where, saved: CONFIG_PATH, via: "browser" }, () =>
+    console.log(`Signed in to ${where}. Saved to ${CONFIG_PATH} (readable only by you).`),
+  );
+}
+
+/** Paste a token made at /account. The flow from before browser sign-in. */
+async function pasteLogin(flags) {
   const { origin } = resolveAuth(flags);
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -303,6 +463,12 @@ async function comments(flags, [ref]) {
       // which passage to change without opening the document.
       console.log(`\n── ${thread.threadId}${thread.section ? `  (${thread.section})` : ""}`);
       if (thread.quote) console.log(`   “${thread.quote}”`);
+      // A suggested edit says what the passage would become, and whether a
+      // person has decided it yet (SPEC §22).
+      if (thread.suggestion) {
+        const change = thread.suggestion.replacement === "" ? "(delete it)" : `“${thread.suggestion.replacement}”`;
+        console.log(`   → ${change}  [${thread.suggestion.state}]`);
+      }
       for (const comment of thread.comments) {
         const via = comment.via && comment.via !== "web" ? ` [via ${comment.via}]` : "";
         console.log(`   ${comment.author}${via}: ${comment.body}`);
@@ -312,6 +478,29 @@ async function comments(flags, [ref]) {
   });
 }
 
+/**
+ * Start a thread on one passage of a document's current version. The passage
+ * is quoted as a reader sees it, as with `suggest`; what to say about it is a
+ * named flag, so the two pieces of free text never run together.
+ */
+async function comment(flags, [ref, ...rest]) {
+  const exact = rest.join(" ");
+  const usage = "usage: bikeshed comment <id> <text> --body <comment> [--prefix …] [--suffix …]";
+  if (!ref || !exact) fail(usage);
+  // An empty --body is what an unset shell variable sends; a thread that says
+  // nothing is a highlight somebody has to resolve for no reason.
+  if (typeof flags.body !== "string" || !flags.body.trim()) fail(usage);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "add_comment", {
+    ...docArgs(ref),
+    exact,
+    body: flags.body,
+    ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
+    ...(typeof flags.suffix === "string" ? { suffix: flags.suffix } : {}),
+  });
+  out(flags.json, result, () => console.log(`opened ${result.threadId}`));
+}
+
 async function reply(flags, [ref, threadId, ...rest]) {
   const body = rest.join(" ");
   if (!ref || !threadId || !body) fail("usage: bikeshed reply <id> <thread> <text>");
@@ -324,6 +513,34 @@ async function reply(flags, [ref, threadId, ...rest]) {
   out(flags.json, result, () => console.log(`replied in ${threadId}`));
 }
 
+/**
+ * Propose new text for one passage of a document's current version. The
+ * passage is quoted as a reader sees it, which is how `comments` prints it, so
+ * a quote can go straight from one command to the other.
+ */
+async function suggest(flags, [ref, ...rest]) {
+  const exact = rest.join(" ");
+  const usage = "usage: bikeshed suggest <id> <text> (--with <new text> | --delete) [--note <why>]";
+  if (!ref || !exact) fail(usage);
+  const replacing = typeof flags.with === "string";
+  if (replacing === Boolean(flags.delete)) fail(usage);
+  // An empty --with is what an unset shell variable sends; deleting a passage
+  // has to be asked for by name.
+  if (replacing && flags.with === "") fail("an empty --with would delete the passage; say --delete if you mean that");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "suggest_edit", {
+    ...docArgs(ref),
+    exact,
+    replacement: replacing ? flags.with : "",
+    ...(typeof flags.note === "string" ? { note: flags.note } : {}),
+    ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
+    ...(typeof flags.suffix === "string" ? { suffix: flags.suffix } : {}),
+  });
+  out(flags.json, result, () =>
+    console.log(`suggested in ${result.threadId}; a person who can approve will accept or reject it`),
+  );
+}
+
 async function folders(flags) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "list_folders", {});
@@ -489,10 +706,10 @@ async function open(flags, [id]) {
   if (!id) fail("usage: bikeshed open <id>");
   const { origin } = resolveAuth(flags);
   const url = `${origin}/d/${id}`;
-  const { spawn } = await import("node:child_process");
-  const opener =
-    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
+  // Best effort, and the address is printed either way. This used to spawn
+  // `start`, which is a cmd.exe builtin rather than a program, so on Windows
+  // the spawn failed and, with nothing listening for the error, crashed.
+  openBrowser(url);
   console.log(url);
 }
 
@@ -527,7 +744,9 @@ const COMMANDS = {
   lineage,
   get,
   comments,
+  comment,
   reply,
+  suggest,
   open,
   folders,
   mkdir,
@@ -557,6 +776,14 @@ async function main() {
       token: { type: "string" },
       limit: { type: "string" },
       cursor: { type: "string" },
+      with: { type: "string" },
+      delete: { type: "boolean", default: false },
+      paste: { type: "boolean", default: false },
+      "no-browser": { type: "boolean", default: false },
+      note: { type: "string" },
+      body: { type: "string" },
+      prefix: { type: "string" },
+      suffix: { type: "string" },
     },
   });
 

package/src/login.mjs

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+// Browser sign-in for the command line: PKCE over a loopback redirect (SPEC §23)
+
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { hostname } from "node:os";
+
+import { CliError } from "./client.mjs";
+
+/**
+ * How `bikeshed login` gets a token without anybody copying one.
+ *
+ * The CLI listens on a random port on 127.0.0.1, opens the deployment's
+ * consent page with that address as the redirect, and waits for the browser
+ * to come back with a one-time code. The code is worth nothing without the
+ * PKCE verifier, which never leaves this process, so a code that leaks through
+ * browser history or another program on the machine cannot be redeemed.
+ *
+ * What comes back is an ordinary personal access token (SPEC §19). The browser
+ * only replaces the copying.
+ */
+
+/** The built-in client the deployment knows without a registration. */
+export const CLI_CLIENT_ID = "bikeshed-cli";
+
+/** How long to wait for the browser before giving up. */
+export const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+export function createPkce() {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+
+export function createState() {
+  return randomBytes(16).toString("base64url");
+}
+
+/**
+ * What the consent page calls this machine, so a person can tell two
+ * terminals apart in their account. A hostname is whatever its owner typed,
+ * so control and formatting characters go, and it is cut to fit a row.
+ */
+export function deviceName(raw = hostname()) {
+  const clean = String(raw ?? "").replace(/[\p{Cc}\p{Cf}]/gu, "").trim();
+  return Array.from(clean).slice(0, 60).join("");
+}
+
+/**
+ * The deployment's authorization server metadata, or null when it predates
+ * browser sign-in.
+ *
+ * "Predates" has two shapes. A 404 is the honest one. Hosting's catch-all
+ * rewrite is the other: it answers a path it does not know with the app's
+ * index.html and a 200, so a body that is not JSON means the same thing as a
+ * 404 (the trap `listSkills` handles too).
+ *
+ * Anything that IS metadata has to describe this deployment and no other. An
+ * endpoint on another origin would send the person, or the code, somewhere
+ * they did not ask to sign in to.
+ */
+export async function discover(origin) {
+  const base = new URL(origin).origin;
+  let res;
+  try {
+    res = await fetch(`${base}/.well-known/oauth-authorization-server`, {
+      headers: { Accept: "application/json" },
+    });
+  } catch (e) {
+    throw new CliError(`could not reach ${base} (${e.cause?.code ?? e.message}).`);
+  }
+  if (res.status === 404) return null;
+  if (!res.ok) throw new CliError(`${base} answered ${res.status} when asked how to sign in.`);
+
+  const meta = await res.json().catch(() => null);
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+
+  const unusable = (why) => new CliError(`${base} describes its sign-in in a way this client cannot use: ${why}.`);
+  if (meta.issuer !== base) {
+    throw unusable(`it calls itself ${JSON.stringify(meta.issuer)}, not ${base}`);
+  }
+  for (const key of ["authorization_endpoint", "token_endpoint"]) {
+    let endpoint;
+    try {
+      endpoint = new URL(meta[key]);
+    } catch {
+      throw unusable(`${key} is not an address`);
+    }
+    if (endpoint.origin !== base) throw unusable(`${key} is on ${endpoint.origin}`);
+  }
+  if (!Array.isArray(meta.code_challenge_methods_supported) || !meta.code_challenge_methods_supported.includes("S256")) {
+    throw unusable("it does not offer S256 PKCE");
+  }
+  return meta;
+}
+
+/** The consent page's address, with every value encoded by URL itself. */
+export function authorizeUrl(endpoint, { clientId, redirectUri, challenge, state, resource, device }) {
+  const url = new URL(endpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("resource", resource);
+  if (device) url.searchParams.set("device", device);
+  return url.toString();
+}
+
+// --- The loopback listener --------------------------------------------------
+
+export const PAGE_HEADERS = {
+  "Content-Type": "text/html; charset=utf-8",
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+  "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'",
+  "X-Content-Type-Options": "nosniff",
+};
+
+const PAGES = {
+  ok: ["Signed in", "You're signed in. You can close this tab and go back to your terminal."],
+  denied: ["Not connected", "You chose not to connect the command line, so nothing was saved. You can close this tab."],
+  failed: ["Sign-in didn't finish", "Go back to your terminal, which says what happened. You can close this tab."],
+};
+
+/**
+ * The page the browser lands on. Fixed text, chosen by kind: nothing from the
+ * query string is ever written into it, so a crafted callback has nothing to
+ * inject into.
+ */
+export function callbackPage(kind) {
+  const [title, text] = PAGES[kind] ?? PAGES.failed;
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} · Bikeshed</title>
+<style>
+  body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 20vh 16px 0; text-align: center; color: #1c1c1c; background: #fafafa; }
+  @media (prefers-color-scheme: dark) { body { color: #ececec; background: #161616; } }
+  h1 { font-size: 1.4rem; margin: 0 0 8px; }
+  p { margin: 0 auto; max-width: 32rem; }
+</style>
+</head>
+<body>
+<h1>${title}</h1>
+<p>${text}</p>
+</body>
+</html>
+`;
+}
+
+function sameSecret(given, expected) {
+  const a = Buffer.from(String(given ?? ""), "utf8");
+  const b = Buffer.from(expected, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * Wait for the browser to come back.
+ *
+ * 127.0.0.1 only, and spelled as that literal in the redirect: `localhost` can
+ * resolve to ::1 first, or to anything a hosts file says. The Host header is
+ * checked too, because a web page that rebinds its own name to 127.0.0.1 can
+ * reach this port, but cannot make its requests say this port's name.
+ *
+ * Only a request carrying this attempt's `state` ends the wait. Anything else
+ * — another path, a stale tab, a forged callback — gets an error page and the
+ * wait goes on. The first request that does carry it is the last one served:
+ * the listener closes before the code is exchanged.
+ */
+export async function listenForCallback({ state, issuer, timeoutMs = LOGIN_TIMEOUT_MS }) {
+  let settle;
+  const result = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  let done = false;
+  let timer;
+  let port;
+
+  const server = createServer((req, res) => {
+    const reply = (status, kind, extra = {}) => {
+      const body = callbackPage(kind);
+      res.writeHead(status, { ...PAGE_HEADERS, "Content-Length": Buffer.byteLength(body), ...extra });
+      res.end(body);
+    };
+
+    if (req.headers.host !== `127.0.0.1:${port}`) return reply(400, "failed");
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+    if (req.method !== "GET" || url.pathname !== "/callback") return reply(404, "failed");
+    if (done || !sameSecret(url.searchParams.get("state"), state)) return reply(400, "failed");
+
+    // This attempt's answer. Whatever it says, it is the only one.
+    done = true;
+    clearTimeout(timer);
+    server.close();
+    res.on("finish", () => server.closeAllConnections());
+
+    const params = url.searchParams;
+    if (params.get("iss") !== issuer) {
+      // A response for this request from some other server is the mix-up
+      // attack RFC 9207 exists for. Its code is not sent anywhere.
+      reply(400, "failed", { Connection: "close" });
+      settle.reject(new CliError("The sign-in came back from a different server than the one you are signing in to. Nothing was saved."));
+      return;
+    }
+    const error = params.get("error");
+    if (error) {
+      reply(200, error === "access_denied" ? "denied" : "failed", { Connection: "close" });
+      const description = params.get("error_description");
+      settle.resolve({ error, ...(description ? { description } : {}) });
+      return;
+    }
+    const code = params.get("code");
+    if (!code) {
+      reply(400, "failed", { Connection: "close" });
+      settle.resolve({ error: "invalid_response", description: "the browser came back without a code" });
+      return;
+    }
+    reply(200, "ok", { Connection: "close" });
+    settle.resolve({ code });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  port = server.address().port;
+
+  const close = (reason) => {
+    clearTimeout(timer);
+    server.close();
+    server.closeAllConnections();
+    if (!done) {
+      done = true;
+      settle.reject(reason ?? new CliError("Sign-in was cancelled. Nothing was saved."));
+    }
+  };
+  timer = setTimeout(
+    () => close(new CliError("Nothing came back from the browser in time. Nothing was saved; run `bikeshed login` to try again.")),
+    timeoutMs,
+  );
+
+  return { redirectUri: `http://127.0.0.1:${port}/callback`, result, close: () => close() };
+}
+
+// --- Opening a browser ------------------------------------------------------
+
+/**
+ * The program that opens a web address, and its arguments.
+ *
+ * Never a shell. On Windows the usual answer is `cmd /c start`, and cmd splits
+ * its command line at `&`, which every query string contains: the browser
+ * would get the address up to the first parameter, and cmd would try to run
+ * the rest as commands. rundll32 takes the whole address as one argument.
+ *
+ * Only http and https, which also rules out an "address" that starts with `-`
+ * and reads to the opener as an option.
+ */
+export function browserCommand(platform, url) {
+  if (typeof url !== "string" || !/^https?:\/\//i.test(url)) {
+    throw new CliError(`refusing to open something that is not a web address: ${url}`);
+  }
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+
+/**
+ * Open a web address, best effort. The caller prints the address either way,
+ * so a missing opener (no xdg-open, a locked-down machine) costs nothing; it
+ * must never crash the command, which an unhandled spawn error would.
+ */
+export function openBrowser(url, platform = process.platform, run = spawn) {
+  try {
+    const [command, args] = browserCommand(platform, url);
+    run(command, args, { stdio: "ignore", detached: true, shell: false })
+      .on("error", () => {})
+      .unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a browser opened from here would be one the person is looking at.
+ * Over SSH it would open on the remote machine, or nowhere; without a display
+ * xdg-open has nothing to open it on.
+ */
+export function canOpenBrowser(env = process.env, platform = process.platform) {
+  if (env.SSH_CONNECTION || env.SSH_TTY) return false;
+  if (platform !== "darwin" && platform !== "win32" && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false;
+  return true;
+}