@tailglow/cli 0.5.1 → 0.6.1

package/src/login-command.js

@@ -0,0 +1,957 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { isCancel, log, select, spinner } from "@clack/prompts";
+import {
+  CLI_CONFIGS,
+  isSameApiUrl,
+  loadConfig,
+  LOGIN_CONFIGS,
+  readPendingLogin,
+  readStoredLogin,
+  resolveApiUrl,
+  resolveCredential,
+  resolveSetting,
+  saveConfig,
+  updateConfig,
+  withConfigLock
+} from "./config.js";
+import { sanitizeText, shouldEmitJson } from "./output.js";
+import { buildRequestHeaders, sendRequest } from "./request.js";
+
+/** Hosts an approval link may use plain http on: a local API and app during development. */
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** `--method` values as typed, mapped to the API's names. */
+const METHOD_FLAGS = { account: "account", "api-key": "api_key" };
+
+/** @type {Record<string, string>} */
+const WITHDRAWN_MESSAGES = {
+  approving_session_ended: "the browser session that approved it ended",
+  user_removed: "the account that approved it no longer exists",
+  account_disabled: "the account that approved it is disabled",
+  team_access_lost: "the approver no longer has that access in the team",
+  team_unavailable: "the team is archived or blocked",
+  team_has_no_project:
+    "an API key needs a team with a project. Create one, or sign in with your account instead"
+};
+
+/**
+ * @typedef {Object} LoginContext
+ * @property {string} config_path
+ * @property {typeof fetch} fetch_impl
+ * @property {() => boolean} is_interactive Whether a person is at the terminal.
+ * @property {(flags: Record<string, unknown>) => boolean} emits_json
+ * @property {() => Promise<"account" | "api_key" | null>} choose_method
+ * @property {(url: string) => void} open_browser
+ * @property {(ms: number) => Promise<void>} sleep
+ * @property {() => number} now
+ * @property {(text: string) => void} say Progress for a person, before the command's result.
+ * @property {{
+ *   start: (text: string, expires_at?: number) => void;
+ *   stop: (text: string, outcome?: "success" | "cancel" | "error") => void;
+ * }} progress
+ * @property {string} device_label
+ */
+
+/**
+ * Opens a URL without a shell. On Windows `start` goes through cmd.exe, which cuts the URL at the
+ * first `&` and drops the code; `rundll32` takes it whole.
+ *
+ * @param {string} url
+ */
+function openBrowser(url) {
+  let command = "xdg-open";
+  let args = [url];
+  if (process.platform === "darwin") command = "open";
+  if (process.platform === "win32") {
+    command = "rundll32";
+    args = ["url.dll,FileProtocolHandler", url];
+  }
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // The link is printed as well, so a machine without a browser loses nothing.
+  }
+}
+
+/**
+ * The approval link, checked before it is stored, printed or opened. Only an https address (http on
+ * this machine) is accepted, so an API the CLI was pointed at cannot make it launch a file or
+ * another program.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function readVerificationUrl(value) {
+  /** @type {URL | null} */
+  let url = null;
+  try {
+    url = new URL(String(value));
+  } catch {
+    url = null;
+  }
+  const is_secure = url?.protocol === "https:";
+  const is_local = url?.protocol === "http:" && LOCAL_HOSTNAMES.has(url.hostname);
+  if (!url || !(is_secure || is_local)) {
+    throw new Error(
+      "The API answered with a sign-in link that is not an https address. Check --api-url."
+    );
+  }
+  return url.href;
+}
+
+/** @returns {LoginContext} */
+export function createLoginContext() {
+  /** @type {ReturnType<typeof spinner> | null} */
+  let indicator = null;
+  /** @type {ReturnType<typeof setInterval> | undefined} */
+  let countdown;
+  return {
+    config_path: CLI_CONFIGS.CONFIG_PATH,
+    fetch_impl: fetch,
+    is_interactive: () => Boolean(process.stdout.isTTY && process.stdin.isTTY),
+    emits_json: (flags) => shouldEmitJson(flags),
+    choose_method: async () => {
+      log.info("Use `tglow help` to browse commands without signing in.");
+      const answer = await select({
+        message: "How do you want to sign in?",
+        options: [
+          {
+            value: "account",
+            label: "Sign in with your Tailglow account"
+          },
+          {
+            value: "api_key",
+            label: "Sign in with an API key"
+          },
+          { value: "cancel", label: "Cancel" }
+        ]
+      });
+      if (isCancel(answer) || answer === "cancel") return null;
+      return answer === "api_key" ? "api_key" : "account";
+    },
+    open_browser: openBrowser,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    say: (text) => log.step(text),
+    progress: {
+      start: (text, expires_at) => {
+        indicator ??= spinner();
+        const message = () => {
+          if (expires_at === undefined) return text;
+          const seconds = Math.max(0, Math.ceil((expires_at - Date.now()) / 1_000));
+          return `${text} (code expires in ${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")})`;
+        };
+        indicator.start(message());
+        clearInterval(countdown);
+        countdown = setInterval(() => indicator?.message(message()), 1_000);
+      },
+      stop: (text, outcome = "success") => {
+        clearInterval(countdown);
+        if (outcome === "cancel") indicator?.cancel(text);
+        else if (outcome === "error") indicator?.error(text);
+        else indicator?.stop(text);
+      }
+    },
+    device_label: hostname()
+  };
+}
+
+/**
+ * Whether a bare command should offer sign-in. This checks local credentials without a request.
+ *
+ * @param {Record<string, unknown>} flags
+ * @param {LoginContext} context
+ */
+export async function shouldOfferLogin(flags, context) {
+  if (flags.help || context.emits_json(flags) || !context.is_interactive()) return false;
+  const config = await loadConfig(context.config_path);
+  if (resolveSetting("api_key", { flags, config })) return false;
+  const login = readStoredLogin(config);
+  return !login || !isSameApiUrl(login.api_url, resolveApiUrl({ flags, config }));
+}
+
+/**
+ * @param {Record<string, unknown>} flags
+ * @param {string} name
+ */
+function readSwitch(flags, name) {
+  const value = flags[name];
+  if (value === undefined || value === false || value === "false") return false;
+  if (value === true || value === "true") return true;
+  throw new Error(`--${name} takes no value, or =true / =false. Received "${String(value)}".`);
+}
+
+/**
+ * Login commands parse only their own flags: `--api-key` means "authenticate with this key"
+ * everywhere else, which is not something a sign-in can use.
+ *
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @param {Set<string>} allowed
+ */
+function refuseUnexpected(words, flags, allowed) {
+  const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown.map((flag) => `--${flag}`).join(", ")}.`
+    );
+  }
+  const extra = words.filter((word) => word !== undefined);
+  if (extra.length > 0) {
+    throw new Error(`Unexpected argument${extra.length === 1 ? "" : "s"}: ${extra.join(", ")}.`);
+  }
+}
+
+/**
+ * @param {{ json: boolean }} view
+ * @param {{ text: string; fields: Record<string, unknown>; code?: number }} result
+ */
+function respond(view, { text, fields, code = 0 }) {
+  return { output: view.json ? JSON.stringify(fields, null, 2) : text, code };
+}
+
+/** @param {import("./types.d.ts").ApiResponse | null} payload @param {number} status */
+function describeRefusal(payload, status) {
+  const message = payload?.error?.message || payload?.message || `HTTP ${status}`;
+  return `${status} ${sanitizeText(String(message))}`;
+}
+
+/**
+ * @param {string} method
+ * @param {LoginContext} context
+ * @param {string} api_url
+ * @returns {Promise<import("./types.d.ts").PendingLogin>}
+ */
+async function startLogin(method, context, api_url) {
+  const { ok, status, payload } = await sendRequest({
+    method: "POST",
+    url: new URL("/v1/auth/cli_logins", api_url),
+    headers: await buildRequestHeaders({ secret: null, team_id: null }),
+    body: { method, device_label: context.device_label },
+    fetch_impl: context.fetch_impl,
+    timeout_ms: LOGIN_CONFIGS.REQUEST_TIMEOUT_MS
+  });
+  if (!ok) throw new Error(`Could not start signing in: ${describeRefusal(payload, status)}`);
+
+  const data = /** @type {Record<string, unknown>} */ (payload?.data ?? {});
+  for (const name of ["id", "user_code", "verification_url", "poll_secret"]) {
+    if (typeof data[name] !== "string") {
+      throw new Error(`The API answered without a ${name}. Check --api-url.`);
+    }
+  }
+
+  const expires_at = Date.parse(String(data.expires_at));
+  if (!Number.isFinite(expires_at)) {
+    throw new Error("The API answered without a valid sign-in expiry. Check --api-url.");
+  }
+  /** @type {import("./types.d.ts").PendingLogin} */
+  const pending = {
+    id: String(data.id),
+    poll_secret: String(data.poll_secret),
+    user_code: String(data.user_code),
+    verification_url: readVerificationUrl(data.verification_url),
+    method: method === "api_key" ? "api_key" : "account",
+    api_url,
+    started_at: context.now(),
+    expires_at
+  };
+  await updateConfig((current) => ({ ...current, pending_login: pending }), context.config_path);
+  return pending;
+}
+
+/**
+ * One poll. Failures that retrying can fix (a network error, a 5xx while the API restarts) come
+ * back as `retry`; everything else is the server's answer.
+ *
+ * @param {import("./types.d.ts").PendingLogin} pending
+ * @param {LoginContext} context
+ * @returns {Promise<{
+ *   status: string;
+ *   status_reason: string | null;
+ *   interval_ms: number;
+ *   credential: Record<string, unknown> | null;
+ * }>}
+ */
+async function pollLogin(pending, context) {
+  /** @param {string} status */
+  const answer = (status) => ({
+    status,
+    status_reason: null,
+    interval_ms: LOGIN_CONFIGS.DEFAULT_INTERVAL_MS,
+    credential: null
+  });
+
+  /** @type {Awaited<ReturnType<typeof sendRequest>>} */
+  let response;
+  try {
+    response = await sendRequest({
+      method: "POST",
+      url: new URL(`/v1/auth/cli_logins/${encodeURIComponent(pending.id)}/token`, pending.api_url),
+      headers: await buildRequestHeaders({ secret: null, team_id: null }),
+      body: { poll_secret: pending.poll_secret },
+      fetch_impl: context.fetch_impl,
+      timeout_ms: LOGIN_CONFIGS.REQUEST_TIMEOUT_MS
+    });
+  } catch {
+    return answer("retry");
+  }
+
+  // The login's key expired in Redis.
+  if (response.status === 404) return answer("expired");
+  if (response.status >= 500) return answer("retry");
+  if (!response.ok) {
+    throw new Error(`Signing in failed: ${describeRefusal(response.payload, response.status)}`);
+  }
+
+  const data = /** @type {Record<string, unknown>} */ (response.payload?.data ?? {});
+  const interval_seconds = Number(data.interval_seconds);
+  const credential =
+    data.credential && typeof data.credential === "object"
+      ? /** @type {Record<string, unknown>} */ (data.credential)
+      : null;
+  return {
+    status: typeof data.status === "string" ? data.status : "retry",
+    status_reason: typeof data.status_reason === "string" ? data.status_reason : null,
+    interval_ms:
+      Number.isFinite(interval_seconds) && interval_seconds > 0
+        ? interval_seconds * 1_000
+        : LOGIN_CONFIGS.DEFAULT_INTERVAL_MS,
+    credential
+  };
+}
+
+/**
+ * Polls until the server gives a final answer or the waiting budget ends. Interactive login makes
+ * one final scheduled poll at expiry to collect a last-moment approval. An in-flight poll is never
+ * cut short: it may be collecting the credential.
+ *
+ * @param {import("./types.d.ts").PendingLogin} pending
+ * @param {LoginContext} context
+ * @param {{ deadline_ms: number; poll_first: boolean; poll_at_deadline?: boolean }} options
+ */
+async function pollUntilAnswered(
+  pending,
+  context,
+  { deadline_ms, poll_first, poll_at_deadline = false }
+) {
+  let interval_ms = LOGIN_CONFIGS.DEFAULT_INTERVAL_MS;
+  let wait_ms = poll_first ? 0 : interval_ms;
+  let last_status = null;
+  while (true) {
+    if (context.now() + wait_ms >= deadline_ms) {
+      if (poll_at_deadline) {
+        // Keep the server's polling interval even when the expiry falls between two polls.
+        if (wait_ms > 0) await context.sleep(wait_ms);
+        const result = await pollLogin(pending, context);
+        if (!["pending", "slow_down", "retry"].includes(result.status)) return result;
+        last_status = result.status;
+      }
+      const status = last_status === "retry" ? "unreachable" : "pending";
+      return { status, status_reason: null, interval_ms, credential: null };
+    }
+    if (wait_ms > 0) await context.sleep(wait_ms);
+
+    const result = await pollLogin(pending, context);
+    last_status = result.status;
+    interval_ms = Math.max(interval_ms, result.interval_ms);
+    if (result.status === "slow_down") interval_ms += LOGIN_CONFIGS.SLOW_DOWN_STEP_MS;
+    if (!["pending", "slow_down", "retry"].includes(result.status)) return result;
+    wait_ms = interval_ms;
+  }
+}
+
+/**
+ * Removes a credential `tglow login` issued, from the API that issued it. Only "that credential no
+ * longer exists" counts as already gone; any other refusal leaves it alive on the server.
+ *
+ * @param {import("./types.d.ts").StoredLogin} login
+ * @param {LoginContext} context
+ * @returns {Promise<"removed" | "already_gone" | "refused" | "unreachable">}
+ */
+async function removeIssuedCredential(login, context) {
+  const is_session = login.type === "session";
+  try {
+    const { ok, status, payload } = await sendRequest({
+      method: is_session ? "POST" : "DELETE",
+      url: new URL(
+        is_session ? "/v1/auth/logout" : `/v1/keys/${encodeURIComponent(login.id)}`,
+        login.api_url
+      ),
+      headers: await buildRequestHeaders({ secret: login.secret, team_id: login.team_id }),
+      body: is_session ? {} : undefined,
+      fetch_impl: context.fetch_impl,
+      timeout_ms: LOGIN_CONFIGS.REQUEST_TIMEOUT_MS
+    });
+    if (ok) return "removed";
+    if (payload?.error?.code === "auth_invalid_credentials") return "already_gone";
+    if (status >= 500) return "unreachable";
+    return "refused";
+  } catch {
+    return "unreachable";
+  }
+}
+
+/** @param {import("./types.d.ts").StoredLogin} login */
+function describeCleanupPlace(login) {
+  return login.type === "session"
+    ? "Profile > Security in the Tailglow app"
+    : "Team settings > API keys in the Tailglow app";
+}
+
+/**
+ * Stores the collected credential, then removes the one it replaces. Saving first means a failed
+ * cleanup can never leave the machine signed out.
+ *
+ * @param {import("./types.d.ts").PendingLogin} pending
+ * @param {Record<string, unknown>} credential
+ * @param {{ json: boolean }} view
+ * @param {LoginContext} context
+ */
+async function finishLogin(pending, credential, view, context) {
+  for (const name of ["secret", "id", "team_id", "user_id", "email"]) {
+    if (typeof credential[name] !== "string") {
+      throw new Error(
+        `The API returned a credential without a ${name}. Run \`tglow login --new\` to start again.`
+      );
+    }
+  }
+
+  /** @type {import("./types.d.ts").StoredLogin} */
+  const login = {
+    type: credential.type === "api_key" ? "api_key" : "session",
+    secret: String(credential.secret),
+    id: String(credential.id),
+    api_url: pending.api_url,
+    team_id: String(credential.team_id),
+    user_id: String(credential.user_id),
+    email: String(credential.email)
+  };
+
+  // A holder rather than a `let`: the assignment happens inside the callback, where TypeScript's
+  // narrowing of a local would lose it.
+  /** @type {{ previous: import("./types.d.ts").StoredLogin | null; is_current: boolean }} */
+  const swap = { previous: null, is_current: false };
+  try {
+    await updateConfig((current) => {
+      // `tglow logout` or `tglow login --new` discarded this sign-in while it waited.
+      if (readPendingLogin(current)?.id !== pending.id) return current;
+      swap.is_current = true;
+      swap.previous = readStoredLogin(current);
+      const { pending_login: _collected, ...rest } = current;
+      return { ...rest, login };
+    }, context.config_path);
+  } catch (err) {
+    // The server has already handed the credential out; ending it beats leaving one nobody holds.
+    const outcome = await removeIssuedCredential(login, context);
+    const fate =
+      outcome === "removed" || outcome === "already_gone"
+        ? "so it was ended"
+        : `and it is still active: remove it in ${describeCleanupPlace(login)}`;
+    throw new Error(
+      `${err instanceof Error ? err.message : String(err)}\n` +
+        `The sign-in was approved, but its credential could not be stored here, ${fate}. Run \`tglow login --new\` to start again.`
+    );
+  }
+
+  if (!swap.is_current) {
+    const outcome = await removeIssuedCredential(login, context);
+    const is_removed = outcome === "removed" || outcome === "already_gone";
+    const text = is_removed
+      ? "This sign-in was cancelled here while it waited, so its credential was ended instead of stored."
+      : `This sign-in was cancelled here while it waited, so its credential was not stored. Remove it in ${describeCleanupPlace(login)}.`;
+    return respond(view, {
+      text,
+      fields: { status: "cancelled", credential_id: login.id, removed: outcome, error: text },
+      code: 1
+    });
+  }
+
+  const replaced = swap.previous;
+  let cleanup = "none";
+  if (replaced && replaced.secret !== login.secret) {
+    cleanup = await removeIssuedCredential(replaced, context);
+  }
+
+  const kind = login.type === "session" ? "CLI session" : "API key";
+  const lines = [
+    `Signed in as ${sanitizeText(login.email)} (team ${sanitizeText(login.team_id)}, ${kind}).`
+  ];
+  if (replaced && (cleanup === "refused" || cleanup === "unreachable")) {
+    lines.push(
+      `Could not remove the credential this replaced. Remove it in ${describeCleanupPlace(replaced)}.`
+    );
+  }
+  lines.push(`Stored in ${context.config_path}, readable only by you.`);
+
+  return respond(view, {
+    text: lines.join("\n"),
+    fields: {
+      status: "signed_in",
+      method: login.type === "session" ? "account" : "api_key",
+      email: login.email,
+      user_id: login.user_id,
+      team_id: login.team_id,
+      credential_id: login.id,
+      replaced_credential: replaced ? cleanup : "none"
+    }
+  });
+}
+
+/**
+ * Clears the pending sign-in, but only if it is still the one this process was working on.
+ *
+ * @param {string} pending_id
+ * @param {LoginContext} context
+ */
+async function forgetPendingLogin(pending_id, context) {
+  await updateConfig((current) => {
+    if (readPendingLogin(current)?.id !== pending_id) return current;
+    const { pending_login: _forgotten, ...rest } = current;
+    return rest;
+  }, context.config_path);
+}
+
+/** @param {{ status: string; status_reason: string | null }} result */
+function describeEnded(result) {
+  if (result.status === "denied") return "The sign-in was denied in the browser.";
+  if (result.status === "expired")
+    return "The sign-in expired before it was approved and collected.";
+  if (result.status === "consumed") {
+    return (
+      "This sign-in was already collected, and a credential is only ever handed out once. " +
+      "If this terminal never received it, remove the unused one in the Tailglow app."
+    );
+  }
+  if (result.status === "revoked") {
+    const why = WITHDRAWN_MESSAGES[result.status_reason ?? ""] ?? "its approval no longer holds";
+    return `The approval was withdrawn: ${why}.`;
+  }
+  return `The sign-in ended (${result.status}).`;
+}
+
+/**
+ * @param {{ json: boolean }} view
+ * @param {{ status: string; status_reason: string | null }} result
+ */
+function respondEnded(view, result) {
+  // A collected sign-in stays pending for the process that collected it, so only --new replaces it.
+  const next = result.status === "consumed" ? "tglow login --new" : "tglow login";
+  const message = `${describeEnded(result)} Run \`${next}\` to start again.`;
+  return respond(view, {
+    text: message,
+    fields: { status: result.status, status_reason: result.status_reason, error: message },
+    code: 1
+  });
+}
+
+/**
+ * @param {{ json: boolean }} view
+ * @param {import("./types.d.ts").PendingLogin} pending
+ */
+function respondUnreachable(view, pending) {
+  const text = `Could not reach ${sanitizeText(pending.api_url)}. The sign-in is kept: check the connection, then run \`tglow login --wait\`.`;
+  return respond(view, {
+    text,
+    fields: { status: "unreachable", api_url: pending.api_url, error: text },
+    code: 1
+  });
+}
+
+/**
+ * @param {{ json: boolean }} view
+ * @param {import("./types.d.ts").PendingLogin} pending
+ * @param {{ code?: number; is_waiting?: boolean }} [options]
+ */
+function respondPending(view, pending, { code = 0, is_waiting = false } = {}) {
+  const next = "tglow login --wait";
+  const opening = is_waiting ? "Still waiting for approval." : "To sign in, open this link:";
+  const link = sanitizeText(pending.verification_url);
+  return respond(view, {
+    text: [
+      opening,
+      ...(is_waiting ? [`Approve it at: ${link}`] : [`  ${link}`]),
+      `Check the page shows the code ${sanitizeText(formatUserCode(pending.user_code))}, then approve it.`,
+      `Then run \`${next}\` to finish. It waits up to ${LOGIN_CONFIGS.WAIT_BUDGET_MS / 1_000} seconds and can be run again.`
+    ].join("\n"),
+    fields: {
+      status: "pending",
+      verification_url: pending.verification_url,
+      user_code: pending.user_code,
+      method: pending.method,
+      next_command: next
+    },
+    code
+  });
+}
+
+/** @param {string} code */
+function formatUserCode(code) {
+  return code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
+}
+
+export function renderLoginHelp() {
+  return [
+    "tglow login: sign in from this machine",
+    "",
+    "Usage:",
+    "  tglow login [--method account|api-key]   Start signing in, in the browser.",
+    "  tglow login --wait                       Finish a sign-in started without a terminal.",
+    "  tglow logout                             Remove the credential tglow login stored.",
+    "  tglow whoami                             Show who the CLI is acting as.",
+    "",
+    "Methods:",
+    "  account   A CLI session that acts as you, in the team you choose. The default.",
+    "  api-key   An API key for one team, with the permissions you choose. The team needs a project.",
+    "",
+    "In a terminal, login opens the approval page and counts down to the code's expiry (ten minutes",
+    "after creation). Expiry ends the interactive wait cleanly; run `tglow login` to try again.",
+    "Without a terminal (an agent, a script), it prints the link and exits; approve it, then run",
+    "`tglow login --wait`.",
+    "",
+    "Flags:",
+    "  --method <account|api-key>  Skip the question.",
+    "  --wait                      Collect a pending sign-in. Exits 0 once signed in, 75 while it is",
+    "                              still waiting (run it again), 1 if it was denied, expired, withdrawn",
+    "                              or the API could not be reached.",
+    "  --new                       Discard a pending sign-in and start another.",
+    "  --api-url <url>             Sign in to another API. The credential is only ever sent there.",
+    "",
+    `The credential is stored in ${CLI_CONFIGS.CONFIG_PATH}, readable only by you.`,
+    "--api-key and TAILGLOW_API_KEY take precedence over it."
+  ].join("\n");
+}
+
+export function describeLoginForMachines() {
+  return {
+    login: {
+      usage: "tglow login [--method account|api-key] [--wait] [--new] [--api-url <url>]",
+      description:
+        "Sign in through the browser. Without a terminal it prints { status: pending, verification_url, user_code } and exits 0; approve the link, then run `tglow login --wait`.",
+      methods: {
+        account: "A CLI session acting as the person, in the team they choose. The default.",
+        "api-key": "An API key for one team with chosen permissions. The team needs a project."
+      },
+      exit_codes: {
+        0: "Signed in, a pending link was printed, or an interactive wait ended normally.",
+        [LOGIN_CONFIGS.EXIT_PENDING]:
+          "The --wait budget ended while approval was pending. Run `tglow login --wait` to resume.",
+        1: "Denied, cancelled, withdrawn or failed; expired when using --wait."
+      }
+    },
+    logout: { usage: "tglow logout", description: "Remove the credential `tglow login` stored." },
+    whoami: {
+      usage: "tglow whoami",
+      description: "Show the person or key, team and credential in use."
+    }
+  };
+}
+
+const LOGIN_FLAGS = new Set(["json", "help", "api-url", "method", "wait", "new"]);
+
+/**
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @param {LoginContext} [context]
+ * @returns {Promise<{ output: string; code: number }>}
+ */
+export async function runLoginCommand(words, flags, context = createLoginContext()) {
+  refuseUnexpected(words, flags, LOGIN_FLAGS);
+  const view = { json: context.emits_json(flags) };
+  if (readSwitch(flags, "help")) {
+    return respond(view, { text: renderLoginHelp(), fields: describeLoginForMachines() });
+  }
+
+  const is_waiting = readSwitch(flags, "wait");
+  const is_new = readSwitch(flags, "new");
+  if (is_waiting && (is_new || flags.method !== undefined)) {
+    throw new Error("--wait finishes the pending sign-in, so it takes no --new or --method.");
+  }
+
+  /** @type {"account" | "api_key" | null} */
+  let requested_method = null;
+  if (flags.method !== undefined) {
+    const method = METHOD_FLAGS[/** @type {keyof typeof METHOD_FLAGS} */ (String(flags.method))];
+    if (!method) {
+      throw new Error(`--method must be account or api-key, received "${String(flags.method)}".`);
+    }
+    requested_method = method === "api_key" ? "api_key" : "account";
+  }
+
+  const config = await loadConfig(context.config_path);
+  const api_url = resolveApiUrl({ flags, config });
+  const interactive = !view.json && context.is_interactive();
+  let pending = readPendingLogin(config);
+  if (pending && context.now() - pending.started_at > LOGIN_CONFIGS.PENDING_FORGET_MS) {
+    await forgetPendingLogin(pending.id, context);
+    pending = null;
+  }
+
+  if (is_waiting) {
+    if (!pending) throw new Error("No sign-in is waiting. Run `tglow login` first.");
+    // The pending sign-in names its own API; only an explicit, different --api-url disagrees.
+    if (typeof flags["api-url"] === "string" && !isSameApiUrl(pending.api_url, api_url)) {
+      throw new Error(
+        `The waiting sign-in is for ${pending.api_url}. Pass --api-url ${pending.api_url}.`
+      );
+    }
+    const result = await pollUntilAnswered(pending, context, {
+      deadline_ms: context.now() + LOGIN_CONFIGS.WAIT_BUDGET_MS,
+      poll_first: true
+    });
+    if (result.status === "pending") {
+      return respondPending(view, pending, { code: LOGIN_CONFIGS.EXIT_PENDING, is_waiting: true });
+    }
+    if (result.status === "unreachable") return respondUnreachable(view, pending);
+    if (result.status === "approved" && result.credential) {
+      return finishLogin(pending, result.credential, view, context);
+    }
+    // Another process holding this sign-in collected it, and that process clears it.
+    if (result.status !== "consumed") await forgetPendingLogin(pending.id, context);
+    return respondEnded(view, result);
+  }
+
+  // A sign-in already waiting is picked up rather than replaced, so a re-run prints the same link
+  // the person may already have open. The server, not the local clock, decides whether it ended.
+  const reusable =
+    pending &&
+    !is_new &&
+    isSameApiUrl(pending.api_url, api_url) &&
+    (requested_method === null || requested_method === pending.method);
+  if (pending && reusable) {
+    let result = await pollLogin(pending, context);
+    // A poll inside the server's interval answers slow_down without reading the sign-in.
+    if (result.status === "slow_down") {
+      await context.sleep(result.interval_ms);
+      result = await pollLogin(pending, context);
+    }
+    if (result.status === "approved" && result.credential) {
+      return finishLogin(pending, result.credential, view, context);
+    }
+    if (["pending", "slow_down", "retry"].includes(result.status)) {
+      if (!interactive) return respondPending(view, pending);
+    } else if (result.status === "consumed") {
+      return respondEnded(view, result);
+    } else {
+      await forgetPendingLogin(pending.id, context);
+      pending = null;
+    }
+  } else {
+    pending = null;
+  }
+
+  if (!pending) {
+    let method = requested_method;
+    if (!method) method = interactive ? await context.choose_method() : "account";
+    if (!method) return { output: "Cancelled.", code: 1 };
+    pending = await startLogin(method, context, api_url);
+    if (!interactive) return respondPending(view, pending);
+  }
+
+  const verification_url = readVerificationUrl(pending.verification_url);
+  context.say(`Opening browser\n${verification_url}`);
+  context.say(`Check the page shows the code ${sanitizeText(formatUserCode(pending.user_code))}.`);
+  context.open_browser(verification_url);
+  const expires_at = Number.isFinite(pending.expires_at)
+    ? Number(pending.expires_at)
+    : pending.started_at + LOGIN_CONFIGS.INTERACTIVE_BUDGET_MS;
+  context.progress.start("Waiting for approval in the browser", expires_at);
+  let result;
+  try {
+    result = await pollUntilAnswered(pending, context, {
+      deadline_ms: expires_at,
+      poll_first: false,
+      poll_at_deadline: true
+    });
+  } finally {
+    let message = "Stopped waiting";
+    if (result?.status === "approved") message = "Approved";
+    else if (result?.status === "pending")
+      message = "Stopped waiting. Run `tglow login --wait` to resume.";
+    else if (result?.status === "expired")
+      message = "Sign-in code expired. Run `tglow login` to try again.";
+    else if (result?.status === "unreachable") message = "Could not reach the API";
+    const outcome =
+      result?.status === "approved"
+        ? "success"
+        : ["pending", "expired"].includes(result?.status ?? "")
+          ? "cancel"
+          : "error";
+    context.progress.stop(message, outcome);
+  }
+
+  if (result.status === "approved" && result.credential) {
+    return finishLogin(pending, result.credential, view, context);
+  }
+  if (result.status === "pending") return { output: "", code: 0 };
+  if (result.status === "unreachable") return respondUnreachable(view, pending);
+  if (result.status !== "consumed") await forgetPendingLogin(pending.id, context);
+  if (result.status === "expired") return { output: "", code: 0 };
+  return respondEnded(view, result);
+}
+
+/**
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @param {LoginContext} [context]
+ * @returns {Promise<{ output: string; code: number }>}
+ */
+export async function runLogoutCommand(words, flags, context = createLoginContext()) {
+  refuseUnexpected(words, flags, new Set(["json", "help"]));
+  const view = { json: context.emits_json(flags) };
+  if (readSwitch(flags, "help")) {
+    return respond(view, { text: renderLoginHelp(), fields: describeLoginForMachines() });
+  }
+
+  // One lock covers reading the login and discarding a pending sign-in, so a `tglow login --wait`
+  // finishing at the same moment is either stored before this read or cancelled by it.
+  const config = await withConfigLock(async () => {
+    const stored = await loadConfig(context.config_path);
+    if (!readPendingLogin(stored)) return stored;
+    const { pending_login: _discarded, ...rest } = stored;
+    await saveConfig(rest, context.config_path);
+    return rest;
+  }, context.config_path);
+
+  const login = readStoredLogin(config);
+
+  if (!login) {
+    const note =
+      typeof config.api_key === "string" || process.env.TAILGLOW_API_KEY
+        ? " An API key from TAILGLOW_API_KEY or `tglow config` is still used; logout removes only what `tglow login` stored."
+        : "";
+    return respond(view, {
+      text: `Not signed in with \`tglow login\`.${note}`,
+      fields: { status: "signed_out", removed: "none" }
+    });
+  }
+
+  const outcome = await removeIssuedCredential(login, context);
+  if (outcome === "unreachable") {
+    return respond(view, {
+      text: `Could not reach ${login.api_url} to end the credential, so it is still stored. Run \`tglow logout\` again.`,
+      fields: { status: "signed_in", removed: outcome, error: "unreachable" },
+      code: 1
+    });
+  }
+
+  await updateConfig((current) => {
+    if (readStoredLogin(current)?.secret !== login.secret) return current;
+    const { login: _removed, ...rest } = current;
+    return rest;
+  }, context.config_path);
+
+  if (outcome === "refused") {
+    return respond(view, {
+      text: `Signed out here, but the API refused to end the credential. Remove it in ${describeCleanupPlace(login)}.`,
+      fields: { status: "signed_out", removed: outcome },
+      code: 1
+    });
+  }
+  const kind = login.type === "session" ? "CLI session" : "API key";
+  let text = `Signed out. The ${kind} has been ended.`;
+  if (outcome === "already_gone") {
+    text = `Signed out. The API no longer accepted this ${kind}, so it was removed here only.`;
+  }
+  return respond(view, { text, fields: { status: "signed_out", removed: outcome } });
+}
+
+/**
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @param {LoginContext} [context]
+ * @returns {Promise<{ output: string; code: number }>}
+ */
+export async function runWhoamiCommand(words, flags, context = createLoginContext()) {
+  refuseUnexpected(words, flags, new Set(["json", "help", "api-key", "api-url", "team"]));
+  const view = { json: context.emits_json(flags) };
+  if (readSwitch(flags, "help")) {
+    return respond(view, { text: renderLoginHelp(), fields: describeLoginForMachines() });
+  }
+
+  const config = await loadConfig(context.config_path);
+  const credential = resolveCredential({ flags, config });
+  const api_url = resolveApiUrl({ flags, config });
+  const team_id = resolveSetting("team", { flags, config }) ?? credential.login?.team_id ?? null;
+
+  /** @param {string | null} selected_team_id */
+  async function readAuth(selected_team_id) {
+    return sendRequest({
+      method: "GET",
+      url: new URL("/v1/auth", api_url),
+      headers: await buildRequestHeaders({ secret: credential.secret, team_id: selected_team_id }),
+      fetch_impl: context.fetch_impl,
+      timeout_ms: LOGIN_CONFIGS.REQUEST_TIMEOUT_MS
+    });
+  }
+
+  let response = await readAuth(team_id);
+  let team_refused = false;
+  // A CLI session removed from its team still identifies the person, which is what they need to
+  // know before signing in again.
+  const is_refused = response.status === 401 || response.status === 403;
+  if (is_refused && credential.login?.type === "session" && team_id) {
+    const identity = await readAuth(null);
+    if (identity.ok) {
+      response = identity;
+      team_refused = true;
+    }
+  }
+  if (!response.ok) throw new Error(describeRefusal(response.payload, response.status));
+
+  const auth = /** @type {Record<string, unknown>} */ (response.payload?.data ?? {});
+  const auth_team_id = typeof auth.team_id === "string" ? auth.team_id : null;
+
+  let team_name = null;
+  if (auth_team_id) {
+    const team = await sendRequest({
+      method: "GET",
+      url: new URL(`/v1/teams/${encodeURIComponent(auth_team_id)}`, api_url),
+      headers: await buildRequestHeaders({ secret: credential.secret, team_id: auth_team_id }),
+      fetch_impl: context.fetch_impl,
+      timeout_ms: LOGIN_CONFIGS.REQUEST_TIMEOUT_MS
+    }).catch(() => null);
+
+    const team_data = /** @type {Record<string, unknown> | undefined} */ (team?.payload?.data);
+    if (team?.ok && typeof team_data?.name === "string") team_name = team_data.name;
+  }
+
+  const is_user = auth.type === "user";
+  let credential_label = "API key";
+  if (credential.login?.type === "session") credential_label = "CLI session (tglow login)";
+  if (credential.login?.type === "api_key") credential_label = "API key (tglow login)";
+  if (credential.source === "env") credential_label = "API key (TAILGLOW_API_KEY)";
+  if (credential.source === "flag") credential_label = "API key (--api-key)";
+
+  const who = is_user
+    ? `${sanitizeText(String(auth.name ?? ""))} <${sanitizeText(String(auth.email ?? ""))}>`
+    : `API key ${sanitizeText(String(auth.name ?? auth.key_id ?? ""))}`;
+
+  let team_line = "No team selected.";
+  if (auth_team_id)
+    team_line = `Team: ${team_name ? `${sanitizeText(team_name)} ` : ""}(${sanitizeText(auth_team_id)})`;
+  if (team_refused)
+    team_line = `No longer a member of team ${sanitizeText(String(team_id))}. Run \`tglow login\` to choose a team.`;
+
+  return respond(view, {
+    text: [
+      `Signed in as ${who}`,
+      team_line,
+      `Credential: ${credential_label}`,
+      `API: ${api_url}`
+    ].join("\n"),
+    fields: {
+      type: is_user ? "user" : "key",
+      user_id: auth.user_id ?? null,
+      email: auth.email ?? null,
+      name: auth.name ?? null,
+      key_id: auth.key_id ?? null,
+      team: auth_team_id ? { id: auth_team_id, name: team_name } : null,
+      team_refused,
+      credential: { source: credential.source, type: credential.login?.type ?? "api_key" },
+      api_url
+    }
+  });
+}