bikeshed-now 0.6.0 → 0.10.0

package/README.md

@@ -10,13 +10,27 @@ 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.
+
+`bikeshed logout` signs this computer out. It revokes a token from browser
+sign-in as well as deleting it. A pasted token is only deleted, because CI may
+be using the same one: revoke it at `/account` once nothing needs it.
 
 ## The loop
 
@@ -27,13 +41,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.6.0",
+  "version": "0.10.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.6.0";
+export const CLIENT_NAME = "bikeshed-cli/0.10.0";
 
 /**
  * Three surfaces, and the split is deliberate rather than untidy.
@@ -165,7 +165,100 @@ 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. */
+/**
+ * Revoke the token being presented, and only it (SPEC §23).
+ *
+ * A 401 from /tokens means one of two things that need different advice: the
+ * token had already stopped working, or the deployment is older than a token
+ * revoking itself and still takes only a browser session there. One call with
+ * the same token to /mcp tells them apart. Returns "revoked", "invalid" or
+ * "unsupported"; a deployment that cannot be reached throws.
+ */
+export async function revokeOwnToken(origin, token) {
+  const res = await fetch(`${origin}/tokens`, {
+    method: "POST",
+    headers: headers(token, { "Content-Type": "application/json" }),
+    body: JSON.stringify({ op: "revoke" }),
+  });
+  if (res.ok) return "revoked";
+  if (res.status !== 401) {
+    throw new CliError(await readError(res, `the server returned ${res.status}`));
+  }
+  const probe = await fetch(`${origin}/mcp`, {
+    method: "POST",
+    headers: headers(token, { "Content-Type": "application/json" }),
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "list_documents", arguments: { limit: 1 } },
+    }),
+  });
+  if (probe.status === 401) return "invalid";
+  if (probe.ok) return "unsupported";
+  throw new CliError(`the server returned ${probe.status}`);
+}
+
 export async function whoami(origin, token) {
   // list_documents is the cheapest authenticated call, and a token that can
   // list is a token that works.

package/src/index.mjs

@@ -11,23 +11,31 @@ import { CONFIG_PATH, readConfig, resolveAuth, writeConfig } from "./config.mjs"
 import {
   CliError,
   callTool,
+  exchangeCode,
   fetchSkill,
   fetchSource,
   listSkills,
+  printable,
+  revokeOwnToken,
   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
- * scripts in `scripts/`. Conflating the two is how somebody runs a teardown
- * against production, so the difference is stated in `--help`, in the README,
- * and here:
- *
- *   scripts/*.mjs   whoever owns the deployment. Admin credentials. Talks to
- *                   Firestore and Storage directly. Provisions and withdraws.
- *   bikeshed        any signed-up user. A personal access token. Talks to the
- *                   deployment over HTTPS. Publishes and revises documents.
+ * A person's own client: their personal access token, over HTTPS, able to do
+ * exactly what they can do in the browser and nothing more.
  *
  * Every command takes `--json`, so it composes inside a script or an agent's
  * shell without anybody parsing human-readable output.
@@ -35,7 +43,8 @@ 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 logout                      sign out (revokes a token from browser sign-in)
   bikeshed list                        documents you can read
   bikeshed publish <file>              create a new document
   bikeshed update <id> <file>          publish a new version
@@ -43,6 +52,8 @@ 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
@@ -92,16 +103,14 @@ Options
   --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
 
 Environment
   BIKESHED_ORIGIN, BIKESHED_TOKEN, BIKESHED_AGENT
-
-This is the end-user tool. The scripts in scripts/ are the OPERATOR tools: they
-use admin credentials, talk to the database directly, and can tear a deployment
-down. They are not the same thing.
 `;
 
 function fail(message) {
@@ -146,7 +155,142 @@ 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);
+  // `via` is what lets `logout` revoke this token: one made by browser sign-in
+  // belongs to this computer alone, where a pasted one may be in CI as well.
+  writeConfig({ ...readConfig(), origin: where, token, via: "browser" });
+
+  // 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 {
@@ -162,13 +306,78 @@ async function login(flags) {
     // Verified before it is stored, so a typo fails here rather than on the
     // next command with a confusing message.
     await whoami(where, token);
-    writeConfig({ ...readConfig(), origin: where, token });
+    writeConfig({ ...readConfig(), origin: where, token, via: "paste" });
     console.log(`\nSaved to ${CONFIG_PATH} (readable only by you).`);
   } finally {
     rl.close();
   }
 }
 
+/**
+ * Sign this computer out.
+ *
+ * Only the SAVED sign-in, never BIKESHED_TOKEN or --token: those belong to a
+ * shell or a job, and revoking one would sign out something nobody meant to
+ * touch. A token from browser sign-in exists for this computer alone, so it is
+ * revoked on the deployment as well as forgotten here. A pasted one may be in
+ * CI too, so it is only forgotten, as is one saved before `login` recorded
+ * which kind it was (SPEC §23).
+ *
+ * The token is forgotten whatever the deployment says, and when it cannot be
+ * reached at all: after `logout`, this computer is signed out. `revoked` in
+ * --json means the deployment confirmed the token no longer works.
+ */
+async function logout(flags) {
+  const config = readConfig();
+  const origin = String(config.origin || resolveAuth().origin).replace(/\/+$/, "");
+  const shadowed = () => {
+    if (process.env.BIKESHED_TOKEN) {
+      console.error("BIKESHED_TOKEN is set in this shell, so commands here still use it. Unset it to sign out here too.");
+    }
+  };
+
+  if (!config.token) {
+    out(flags.json, { origin, revoked: false, forgot: false }, () => console.log("Not signed in on this computer."));
+    shadowed();
+    return;
+  }
+
+  let outcome = "kept";
+  let why = "You pasted it in, so something else may use it too.";
+  if (config.via === "browser") {
+    try {
+      outcome = await revokeOwnToken(origin, config.token);
+      why = `${origin} is too old to revoke a token from the command line.`;
+    } catch (e) {
+      outcome = "failed";
+      why =
+        e instanceof CliError
+          ? `${origin} did not revoke it (${printable(e.message, 80)}).`
+          : `Could not reach ${origin} to revoke it (${printable(e.cause?.code ?? e.message, 80)}).`;
+    }
+  }
+
+  const kept = { ...config, origin };
+  delete kept.token;
+  delete kept.via;
+  writeConfig(kept);
+
+  const revoked = outcome === "revoked" || outcome === "invalid";
+  out(flags.json, { origin, revoked, forgot: true }, () =>
+    console.log(
+      outcome === "revoked"
+        ? `Signed out. ${origin} revoked the token, and it is gone from this computer.`
+        : outcome === "invalid"
+          ? `Signed out. The token had already stopped working on ${origin}, and it is gone from this computer.`
+          : "Signed out. The token is gone from this computer.",
+    ),
+  );
+  if (!revoked) {
+    console.error(`${why} It still works until you revoke it at ${origin}/account, under Access tokens.`);
+  }
+  shadowed();
+}
+
 async function list(flags) {
   const { origin, token } = resolveAuth(flags);
   const page = (limit, cursor) => {
@@ -327,6 +536,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>");
@@ -532,10 +764,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);
 }
 
@@ -563,6 +795,7 @@ async function watchFile(file, run) {
 
 const COMMANDS = {
   login,
+  logout,
   list,
   publish,
   update,
@@ -570,6 +803,7 @@ const COMMANDS = {
   lineage,
   get,
   comments,
+  comment,
   reply,
   suggest,
   open,
@@ -580,7 +814,7 @@ const COMMANDS = {
 };
 
 /** Commands that reach a deployment without authenticating as anybody. */
-const NO_TOKEN = new Set(["login", "open", "skills"]);
+const NO_TOKEN = new Set(["login", "logout", "open", "skills"]);
 
 async function main() {
   const { values, positionals } = parseArgs({
@@ -603,7 +837,10 @@ async function main() {
       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;
+}