@monster-orange/den 0.4.4 → 0.4.6

package/src/ui/cli/web-command.ts

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { execFileSync, spawn, spawnSync } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
+import * as net from "net";
 import * as path from "path";
 import { pathToFileURL } from "url";
 import { CLI_SPAWN_TIMEOUT_MS, DEFAULT_PORT } from "../../shared/constants.js";
@@ -20,7 +21,9 @@ import {
   readWebSecret,
   rotateWebSecret,
 } from "../../shared/web-secret.js";
+import { newConfirmCode } from "../../shared/confirm-code.js";
 import {
+  checkLoginCode,
   ignoredConfigWarning,
   localhostOrigin,
   loginLink,
@@ -35,6 +38,24 @@ import { revokeAllActorTokens } from "../../shared/actor-token.js";
 import { engineBin, engineModuleFile } from "../../shared/engine.js";
 import { readEdgeConfig, readWebPort } from "../../shared/edge/config.js";
 import { webRouteHosts } from "../../shared/edge/render.js";
+import {
+  expiringTokenWarning,
+  GITHUB_DEVICE_PAGE,
+  githubClientId,
+  githubEndpoints,
+  noClientIdMessage,
+} from "../../shared/github-app.js";
+import {
+  githubDeviceClient,
+  githubPrincipal,
+  runDeviceFlow,
+  type GithubDeviceClient,
+} from "../../shared/github-device.js";
+import {
+  clearWebOwner,
+  readWebOwner,
+  writeWebOwner,
+} from "../../shared/web-owner.js";
 import {
   ownServer,
   processCwd,
@@ -225,6 +246,24 @@ export function buildDenWebUrl(
   return `http://${resolveDenWebHost(hostsContent)}:${port}`;
 }
 
+/**
+ * The address `web up` names: the bound one when DEN_BIND_HOST is a
+ * specific address beyond loopback (a LAN-only bind doesn't answer on
+ * localhost), else buildDenWebUrl's.
+ */
+export function webUpUrl(
+  port: number,
+  bind: string | undefined = process.env.DEN_BIND_HOST,
+  hostsContent?: string,
+): string {
+  const to = webProbeTarget(bind, port);
+  const loopback =
+    to.host === "::1" || /^127\./.test(to.host) || to.host === "localhost";
+  return loopback
+    ? buildDenWebUrl(port, hostsContent)
+    : `http://${to.hostHeader}`;
+}
+
 export function denWebUrlAliases(port: number): string[] {
   return [
     `http://${product().cli}:${port}`,
@@ -252,6 +291,29 @@ export function isDenWebTabUrl(rawUrl: string, port: number): boolean {
   }
 }
 
+/**
+ * Where `web up`'s probes (readiness, the CLI's own calls) reach the
+ * server, and the Host they send: the address DEN_BIND_HOST binds. Unset,
+ * 0.0.0.0 or `::` answer on loopback, so 127.0.0.1; one specific address
+ * (a LAN IP with web.allow_plain_http_remote, or ::1) answers only there.
+ * The Host names that address (an IPv6 one bracketed): the Host allowlist
+ * accepts it (a loopback name, or the bound LAN address).
+ */
+export function webProbeTarget(
+  bind: string | undefined,
+  port: number,
+): { host: string; hostHeader: string } {
+  const b = (bind ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "");
+  const host = b === "" || b === "0.0.0.0" || b === "::" ? "127.0.0.1" : b;
+  return {
+    host,
+    hostHeader: `${net.isIPv6(host) ? `[${host}]` : host}:${port}`,
+  };
+}
+
 async function getHttpText(
   port: number,
   requestPath: string,
@@ -266,12 +328,18 @@ async function getHttpText(
       resolve(value);
     };
 
+    const to = webProbeTarget(process.env.DEN_BIND_HOST, port);
     const req = http.get(
       {
-        host: "127.0.0.1",
+        host: to.host,
         port,
         path: requestPath,
         timeout: 1_500,
+        agent: false,
+        setHost: false,
+        // The CLI's bearer, as serverCall sends: an address beyond loopback
+        // answers an unsigned probe 401 signin_required, never ready.
+        headers: { host: to.hostHeader, ...cliAuthHeaders() },
       },
       (res) => {
         let body = "";
@@ -1072,6 +1140,8 @@ export const WEB_SUBCOMMANDS_WITH_HELP = [
   "login",
   "sessions",
   "logout",
+  "owner",
+  "approve",
 ] as const;
 
 export function displayWebHelp(): void {
@@ -1082,12 +1152,16 @@ export function displayWebHelp(): void {
   console.log(`  ${product().cli} web --setup-browser-access`);
   console.log(`  ${product().cli} web token --print`);
   console.log(
-    `  ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--port <port>]`,
+    `  ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--no-wait] [--port <port>]`,
   );
   console.log(`  ${product().cli} web sessions [--json] [--port <port>]`);
   console.log(
     `  ${product().cli} web logout [<id prefix>] [--all] [--port <port>]`,
   );
+  console.log(`  ${product().cli} web owner [link|show|unlink] [--json]`);
+  console.log(
+    `  ${product().cli} web approve <code> | --list [--json] [--port <port>]`,
+  );
   console.log();
   console.log(chalk.bold("Actions:"));
   console.log(
@@ -1101,7 +1175,7 @@ export function displayWebHelp(): void {
     "  open               Start if needed, and sign this browser in (a new tab)",
   );
   console.log(
-    "  login              Print a one-time sign-in link (60 s), for another browser",
+    "  login              Print a one-time sign-in link (60 s) and its code, then wait until it's used",
   );
   console.log("  sessions           List the signed-in browsers");
   console.log(
@@ -1110,12 +1184,19 @@ export function displayWebHelp(): void {
   console.log(
     "  token --print      Print your CLI token, for curl (Authorization: Bearer …)",
   );
+  console.log(
+    "  owner link         Link your GitHub account as this Den's owner (Sign in with GitHub)",
+  );
+  console.log(
+    "  approve <code>     Let in a computer whose signed-out page shows this code",
+  );
   console.log("  (start/stop remain accepted as legacy aliases for up/down)");
   console.log();
   console.log(chalk.bold("Options:"));
   console.log("  --port, -p <port>  Use a non-default web port");
   console.log(
     "  --no-open          Start or check the server without opening a browser",
+    "  --json             (up, restart) log on stderr; stdout: { ok, url, port, version? }",
   );
   console.log(
     "  --setup-browser-access  Request macOS Automation access for browser tab reuse",
@@ -1174,7 +1255,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
     return;
   }
   if (args[0] === "login") {
-    process.exitCode = cmdWebLogin(args.slice(1));
+    process.exitCode = await cmdWebLoginWait(args.slice(1));
     return;
   }
   if (args[0] === "sessions") {
@@ -1185,6 +1266,14 @@ export async function cmdWeb(args: string[]): Promise<void> {
     process.exitCode = await cmdWebLogout(args.slice(1));
     return;
   }
+  if (args[0] === "owner") {
+    process.exitCode = await cmdWebOwner(args.slice(1));
+    return;
+  }
+  if (args[0] === "approve") {
+    process.exitCode = await cmdWebApprove(args.slice(1));
+    return;
+  }
   if (args.includes("--help") || args.includes("-h")) {
     displayWebHelp();
     return;
@@ -1196,7 +1285,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
     return;
   }
 
-  const url = buildDenWebUrl(options.port);
+  const url = webUpUrl(options.port);
 
   // Never act on another distribution's server: not "already running", and
   // never a signal to it (down, restart).
@@ -1392,31 +1481,19 @@ function takePort(args: string[]): { port: number; rest: string[] } {
   return { port, rest };
 }
 
-/**
- * `<cli> web login [--next <path>] [--host <name> | --origin <url>]`: a fresh sign-in link
- * on stdout, alone (the only place a login code is ever printed); a note on
- * stderr. `--host` for an edge hostname (its URL from the edge config),
- * `--origin` for any allowed origin (a LAN name), where the cookie must be
- * set (the signed-out page there says which).
- */
-export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
-  const usage = `Usage: ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--port <port>]\n`;
-  if (isHelp(args)) {
-    io.out(
-      usage +
-        "  Prints a one-time sign-in link (it works once, within 60 s) for one browser.\n" +
-        "  On localhost nothing asks for a sign-in; it is needed when this server is\n" +
-        "  reached from another machine (pass the edge hostname as --host, or a LAN\n" +
-        "  address as --origin).\n" +
-        "  --next <path>   where the browser lands after signing in (same origin only)\n" +
-        "  --host <name>   an edge hostname that routes here (an edge domain or alias,\n" +
-        "                  a VPN name among them): the link uses its edge URL\n" +
-        "  --origin <url>  the address the browser uses, http(s)://host[:port]\n",
-    );
-    return 0;
-  }
+const LOGIN_USAGE = () =>
+  `Usage: ${product().cli} web login [--next <path>] [--host <name> | --origin <url>] [--no-wait] [--port <port>]\n`;
+
+/** `web login`'s arguments, or an exit code (usage or a bad value, already said). */
+function parseLoginArgs(
+  args: string[],
+  io: CliIo,
+):
+  | { port: number; next: string; origin: string | null; noWait: boolean }
+  | number {
   let next = "/";
   let origin: string | null = null;
+  let noWait = false;
   let port: number;
   let rest: string[];
   try {
@@ -1433,6 +1510,10 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
         : a.startsWith(`${flag}=`)
           ? a.slice(flag.length + 1)
           : undefined;
+    if (a === "--no-wait") {
+      noWait = true;
+      continue;
+    }
     const n = val("--next");
     const o = val("--origin");
     const h = val("--host");
@@ -1453,14 +1534,46 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
         return 2;
       }
     } else {
-      io.err(usage);
+      io.err(LOGIN_USAGE());
       return 2;
     }
   }
+  return { port, next, origin, noWait };
+}
+
+const LOGIN_HELP = () =>
+  LOGIN_USAGE() +
+  "  Prints a one-time sign-in link (open it within 60 s) for one browser, and a\n" +
+  "  code the page behind the link asks for, then waits until the link is used:\n" +
+  '  "Signed in: <browser> (<address>) at <time>", or "Expired: nobody used the\n' +
+  '  link" (exit 1). On localhost nothing asks for a sign-in; it is needed when\n' +
+  "  this server is reached from another machine (pass the edge hostname as\n" +
+  "  --host, or a LAN address as --origin).\n" +
+  "  --next <path>   where the browser lands after signing in (same origin only)\n" +
+  "  --host <name>   an edge hostname that routes here (an edge domain or alias,\n" +
+  "                  a VPN name among them): the link uses its edge URL\n" +
+  "  --origin <url>  the address the browser uses, http(s)://host[:port]\n" +
+  "  --no-wait       print the link and exit; the link signs in by itself, no\n" +
+  "                  code (for scripts)\n";
+
+/**
+ * `<cli> web login --no-wait`: a fresh sign-in link on stdout, alone (the
+ * only place a login code is ever printed); a note on stderr. `--host` for
+ * an edge hostname (its URL from the edge config), `--origin` for any
+ * allowed origin (a LAN name), where the cookie must be set (the
+ * signed-out page there says which). The link signs in when opened.
+ */
+export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
+  if (isHelp(args)) {
+    io.out(LOGIN_HELP());
+    return 0;
+  }
+  const a = parseLoginArgs(args, io);
+  if (typeof a === "number") return a;
   const link = freshLoginLink(
-    port,
-    next,
-    origin ?? localhostOrigin(port),
+    a.port,
+    a.next,
+    a.origin ?? localhostOrigin(a.port),
     io.stateDir ?? getStateDir(),
   );
   io.err(
@@ -1470,6 +1583,121 @@ export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
   return 0;
 }
 
+/** "10:42" in this machine's time. */
+function clockTime(iso: string): string {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime())
+    ? iso
+    : `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+/**
+ * `<cli> web login` (SEC-2a): the link and an 8-character code, then a
+ * wait until the link is used or expires. The page behind the link asks
+ * for the code before it signs anything in. The CLI registers the link's
+ * nonce and the code with the running server (its bearer) and polls that
+ * wait; the code is shown here only, never logged. With no server running
+ * (or `--no-wait`) it prints the link alone, as before.
+ */
+export async function cmdWebLoginWait(
+  args: string[],
+  io: CliIo = stdIo,
+  opts: { pollMs?: number; maxWaitMs?: number } = {},
+): Promise<number> {
+  if (isHelp(args)) {
+    io.out(LOGIN_HELP());
+    return 0;
+  }
+  const a = parseLoginArgs(args, io);
+  if (typeof a === "number") return a;
+  if (a.noWait)
+    return cmdWebLogin(
+      args.filter((x) => x !== "--no-wait"),
+      io,
+    );
+  const stateDir = io.stateDir ?? getStateDir();
+  const secret = ensureWebSecret(stateDir);
+  const now = Date.now();
+  const loginCode = mintLoginCode(secret, now);
+  const checked = checkLoginCode(loginCode, secret, now);
+  if (!checked.ok) {
+    io.err(`${product().cli}: could not make a sign-in link\n`);
+    return 1;
+  }
+  const confirm = newConfirmCode();
+  const reg = await serverCall(stateDir, a.port, "POST", "/api/web/logins", {
+    nonce: checked.nonce,
+    code: confirm,
+    expiresAt: checked.expiresAt,
+  });
+  const link = loginLink(
+    a.origin ?? localhostOrigin(a.port),
+    loginCode,
+    a.next,
+  );
+  if (!reg) {
+    io.err(
+      `${product().cli}: no ${product().title} web server answers on port ${a.port}, so this ` +
+        "doesn't wait and the link asks for no code (as --no-wait). Start the server " +
+        `(\`${product().cli} web up\`), then open this link within 60 seconds; it signs in one browser, once.\n`,
+    );
+    io.out(`${link}\n`);
+    return 0;
+  }
+  const id = (reg.json as { id?: unknown } | null)?.id;
+  if (reg.status !== 200 || typeof id !== "string") {
+    io.err(`${product().cli}: ${apiError(reg)}\n`);
+    return 1;
+  }
+  io.err(
+    `${product().cli}: open this link within 60 seconds, in the browser to sign in. ` +
+      `It asks for this code: ${confirm}\n`,
+  );
+  io.out(`${link}\n`);
+  io.err(`${product().cli}: waiting for the link to be used…\n`);
+  const pollMs = opts.pollMs ?? 1000;
+  const deadline = Date.now() + (opts.maxWaitMs ?? 7 * 60_000);
+  for (;;) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    const r = await serverCall(
+      stateDir,
+      a.port,
+      "GET",
+      `/api/web/logins/${id}`,
+    );
+    const j = (r?.json ?? {}) as {
+      state?: string;
+      device?: string;
+      client?: string;
+      usedAt?: string;
+    };
+    if (r && j.state === "used") {
+      io.out(
+        `Signed in: ${j.device ?? "a browser"}${j.client ? ` (${j.client})` : ""}` +
+          ` at ${clockTime(j.usedAt ?? new Date().toISOString())}\n`,
+      );
+      return 0;
+    }
+    if (r && j.state === "refused") {
+      io.err("Refused: too many wrong codes; the link no longer works\n");
+      return 1;
+    }
+    if (
+      (r && (j.state === "expired" || r.status === 404)) ||
+      Date.now() > deadline
+    ) {
+      io.err("Expired: nobody used the link\n");
+      return 1;
+    }
+    if (!r) {
+      io.err(
+        `${product().cli}: the server stopped answering; the link can't be used now\n`,
+      );
+      return 1;
+    }
+  }
+}
+
 /**
  * `web login --host <name>`: the origin a browser uses for an edge hostname
  * that routes to this server (edge.routes under any edge domain or alias),
@@ -1523,14 +1751,17 @@ function serverCall(
 ): Promise<{ status: number; json: unknown } | null> {
   return new Promise((resolve) => {
     const payload = body === undefined ? undefined : JSON.stringify(body);
+    const to = webProbeTarget(process.env.DEN_BIND_HOST, port);
     const req = http.request(
       {
-        host: "127.0.0.1",
+        host: to.host,
         port,
         path: p,
         method,
         timeout: 10_000,
+        setHost: false,
         headers: {
+          host: to.hostHeader,
           ...cliAuthHeaders(stateDir),
           ...(payload !== undefined
             ? {
@@ -1737,3 +1968,252 @@ export async function cmdWebLogout(
   );
   return 0;
 }
+
+// ── SEC-2a: approve this computer with a code (`web approve`) ──────────────
+
+interface WaitingRow {
+  code: string;
+  device: string;
+  client?: string;
+  createdAt: string;
+  expiresAt: string;
+}
+
+/** "3 min ago" for a list: whole minutes, or "just now". */
+function agoText(iso: string, now = Date.now()): string {
+  const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+  return s < 60 ? "just now" : `${Math.round(s / 60)} min ago`;
+}
+
+/**
+ * `<cli> web approve <code> | --list [--json]`: let in a computer whose
+ * signed-out page shows `<code>` (case and dashes don't matter), or list
+ * the ones waiting. It asks the running server, with this CLI's bearer:
+ * the requests live in its memory only, so with no server there is
+ * nothing to approve.
+ */
+export async function cmdWebApprove(
+  args: string[],
+  io: CliIo = stdIo,
+): Promise<number> {
+  let port: number;
+  let rest: string[];
+  try {
+    ({ port, rest } = takePort(args));
+  } catch (e) {
+    io.err(`${(e as Error).message}
+`);
+    return 2;
+  }
+  const usage = `Usage: ${product().cli} web approve <code> | --list [--json] [--port <port>]\n`;
+  if (isHelp(rest)) {
+    io.out(
+      usage +
+        "  Lets in the computer whose signed-out page shows <code> (like K7Q-42M; case\n" +
+        "  and dashes don't matter). That page then signs in by itself. A code lasts\n" +
+        "  10 minutes and works once.\n" +
+        "  --list   the computers waiting: code, browser, address, age\n" +
+        "  --json   with --list: as JSON\n",
+    );
+    return 0;
+  }
+  const list = rest.includes("--list");
+  const asJson = rest.includes("--json");
+  const codes = rest.filter((a) => a !== "--list" && a !== "--json");
+  if (
+    codes.some((a) => a.startsWith("-")) ||
+    (list ? codes.length !== 0 : codes.length !== 1 || asJson)
+  ) {
+    io.err(usage);
+    return 2;
+  }
+  const stateDir = io.stateDir ?? getStateDir();
+  const r = list
+    ? await serverCall(stateDir, port, "GET", "/api/web/waiting")
+    : await serverCall(stateDir, port, "POST", "/api/web/approve", {
+        code: codes[0],
+      });
+  if (!r) {
+    io.err(
+      `${product().cli}: no ${product().title} web server answers on port ${port}. ` +
+        "A waiting computer's code lives in the running server: start it " +
+        `(\`${product().cli} web up\`) and reload the page on the other computer.\n`,
+    );
+    return 1;
+  }
+  if (r.status !== 200) {
+    io.err(`${product().cli}: ${apiError(r)}\n`);
+    return 1;
+  }
+  if (list) {
+    const rows = ((r.json as { waiting?: WaitingRow[] }).waiting ?? []).map(
+      (w) => ({ ...w }),
+    );
+    if (asJson) {
+      io.out(`${JSON.stringify(rows, null, 2)}\n`);
+      return 0;
+    }
+    if (rows.length === 0) {
+      io.out("No computers are waiting for approval.\n");
+      return 0;
+    }
+    const table = [
+      ["CODE", "BROWSER", "ADDRESS", "WAITING"],
+      ...rows.map((w) => [
+        w.code,
+        w.device,
+        w.client ?? "",
+        agoText(w.createdAt),
+      ]),
+    ];
+    const widths = table[0].map((_, c) =>
+      Math.max(...table.map((row) => row[c].length)),
+    );
+    for (const row of table)
+      io.out(
+        `${row
+          .map((cell, c) =>
+            c === row.length - 1 ? cell : cell.padEnd(widths[c]),
+          )
+          .join("  ")
+          .trimEnd()}\n`,
+      );
+    return 0;
+  }
+  const w = r.json as WaitingRow;
+  io.out(
+    `Approved: ${w.device}${w.client ? ` (${w.client})` : ""}. ` +
+      "Its page signs in by itself.\n",
+  );
+  return 0;
+}
+
+// ── SEC-2a: the owner (`web owner link`, `show`, `unlink`) ─────────────────
+
+/**
+ * `<cli> web owner [link|show|unlink] [--json]`: the GitHub account this
+ * Den belongs to, which Sign in with GitHub admits.
+ *  - link: GitHub's device flow, here in the terminal: the code and
+ *    github.com/login/device, then a wait while you approve it. Den keeps
+ *    `github:<id>` and the login (a 0600 file in the state dir) and drops
+ *    the token at once. Refused while an owner is linked.
+ *  - show (the default): who it is.
+ *  - unlink: forget it. Signed-in browsers stay signed in.
+ * `client` and `sleep` are a test's.
+ */
+export async function cmdWebOwner(
+  args: string[],
+  io: CliIo & {
+    client?: GithubDeviceClient;
+    sleep?: (ms: number) => Promise<void>;
+    clientId?: string;
+  } = stdIo,
+): Promise<number> {
+  const usage = `Usage: ${product().cli} web owner [link|show|unlink] [--json]\n`;
+  if (isHelp(args)) {
+    io.out(
+      usage +
+        "  link    link your GitHub account as this Den's owner (GitHub's device flow:\n" +
+        `          enter the code it shows at ${GITHUB_DEVICE_PAGE}); only its id is kept\n` +
+        "  show    who the owner is (the default)\n" +
+        "  unlink  forget the owner; signed-in browsers stay signed in\n" +
+        "  The owner can then sign in from any device: the signed-out page's\n" +
+        "  Sign in with GitHub. No token is stored.\n",
+    );
+    return 0;
+  }
+  const asJson = args.includes("--json");
+  const rest = args.filter((a) => a !== "--json");
+  const sub = rest[0] ?? "show";
+  if (rest.length > 1 || !["link", "show", "unlink"].includes(sub)) {
+    io.err(usage);
+    return 2;
+  }
+  const stateDir = io.stateDir ?? getStateDir();
+  const cli = product().cli;
+  if (sub === "show") {
+    const o = readWebOwner(stateDir);
+    if (asJson) io.out(`${JSON.stringify({ owner: o }, null, 2)}\n`);
+    else
+      io.out(
+        o
+          ? `Owner: @${o.login} (${o.owner}), linked ${o.linkedAt.replace("T", " ").replace(/\.\d+Z$/, "Z")}.\n`
+          : `No owner is linked. Run \`${cli} web owner link\`.\n`,
+      );
+    return 0;
+  }
+  if (sub === "unlink") {
+    const was = clearWebOwner(stateDir);
+    if (asJson) io.out(`${JSON.stringify({ unlinked: was }, null, 2)}\n`);
+    else
+      io.out(
+        was
+          ? `Unlinked @${was.login}. Signed-in browsers stay signed in (\`${cli} web logout\` ends them).\n`
+          : "No owner was linked.\n",
+      );
+    return 0;
+  }
+  const linked = readWebOwner(stateDir);
+  if (linked) {
+    io.err(
+      `${cli}: this Den's owner is @${linked.login} already; \`${cli} web owner unlink\` first.\n`,
+    );
+    return 1;
+  }
+  let clientId = io.clientId;
+  if (clientId === undefined) {
+    try {
+      clientId = githubClientId(
+        readWebAuthConfig(getDistRoot(), product().configFile).githubClientId,
+      );
+    } catch (e) {
+      io.err(`${cli}: ${(e as Error).message}\n`);
+      return 1;
+    }
+  }
+  if (!clientId) {
+    io.err(`${cli}: ${noClientIdMessage(cli)}\n`);
+    return 1;
+  }
+  const ep = githubEndpoints();
+  let outcome;
+  try {
+    outcome = await runDeviceFlow({
+      clientId,
+      client: io.client ?? githubDeviceClient(ep),
+      ...(io.sleep ? { sleep: io.sleep } : {}),
+      minIntervalMs: ep.fake || io.client ? 0 : 1000,
+      onCode: (c) =>
+        io.out(
+          `Open ${GITHUB_DEVICE_PAGE} and enter this code:\n\n    ${c.userCode}\n\n` +
+            `Waiting for you to approve it on GitHub (it asks for no permissions; ` +
+            `the code lasts ${Math.round(c.expiresIn / 60)} min)…\n`,
+        ),
+    });
+  } catch (e) {
+    io.err(`${cli}: ${(e as Error).message}\n`);
+    return 1;
+  }
+  if (outcome.kind !== "ok") {
+    io.err(
+      `${cli}: ${
+        outcome.kind === "expired"
+          ? "the code expired before it was approved; run it again"
+          : outcome.kind === "denied"
+            ? "the request was cancelled on GitHub"
+            : outcome.message
+      }\n`,
+    );
+    return 1;
+  }
+  const rec = writeWebOwner(outcome.identity, stateDir);
+  if (outcome.expiringToken)
+    io.err(`${product().cli}: warning: ${expiringTokenWarning()}\n`);
+  if (asJson) io.out(`${JSON.stringify({ owner: rec }, null, 2)}\n`);
+  else
+    io.out(
+      `Linked @${rec.login} (${githubPrincipal(outcome.identity.id)}) as this Den's owner; ` +
+        "the token was not kept. Sign in with GitHub from your other devices now works.\n",
+    );
+  return 0;
+}