@plotio/cli 0.1.0 → 0.2.1

package/README.md

@@ -26,22 +26,46 @@ as a hash:
   a one-time `temp_code_…` (ten minutes, single use).
   `plot open temp_code_… --agent "Claude Code"` redeems it for a token that
   reads that one page (24 hours from the last read, a week at most).
-- **A workspace.** `plot login --agent "Claude Code"` mints a token on this
-  machine, opens `<site>/connect?hash=…&agent=…&fp=…` for a person to approve,
-  and waits up to ten minutes. Only the hash goes to the browser. The terminal
-  prints a six-character code (the hash's first six characters) and the page
-  asks the person to type it, so a link sent on by someone else cannot be
-  approved by mistake. The URL is printed too, for SSH and sandboxes. The site
-  is `--site`, else `PLOT_SITE_URL`, else the web app the API names in its
-  OAuth metadata, so `--api` at a local or preview deployment approves there
-  rather than on production.
+- **A workspace.** `plot login --agent "Claude Code"` signs in the way Claude
+  Code does: OAuth authorization code with PKCE (S256), client id `plot-cli`,
+  against the authorization server the API names in
+  `/.well-known/oauth-authorization-server`. So `--api` at a local or preview
+  deployment signs in on that deployment's own web app, never production's.
+  The code is exchanged at the token endpoint, `/v1/me` names the workspace,
+  and the token is stored as that API's workspace grant.
+
+One verifier and state make two authorize URLs that differ only in
+`redirect_uri`, and the server binds a code to the one it was approved with:
+a loopback one (`http://127.0.0.1:<port>/callback`) and the out-of-band
+`urn:ietf:wg:oauth:2.0:oob`, for which the consent page shows the code
+instead of redirecting. The loopback URL is only ever opened, never printed,
+because a browser on any other machine would be redirected into a dead port.
+
+- **On your own machine.** The browser opens on the loopback URL; approve
+  and it calls the terminal back by itself. Nothing to paste.
+- **Browser elsewhere (SSH, another computer).** The terminal prints the
+  out-of-band URL under "A browser tab should have opened. If it did not, or
+  it is on another machine, open this URL:". Approve there, and paste the
+  code the page shows at `Paste code here if prompted:`. Whichever arrives
+  first wins, within ten minutes. `--no-browser` prints only that URL and
+  does not listen at all.
+- **An agent or a sandbox (no TTY).** Nothing listens and nothing waits.
+  `plot login` prints the out-of-band URL and
+  `After approving, run: plot login --code <code>`, saves a pending login
+  (API base, verifier, state, agent name, time) in
+  `$XDG_CONFIG_HOME/plot/pending-login.json` at `0600`, and exits 0. The agent
+  hands the URL to its person, who approves and sends the code back;
+  `plot login --code <code>` exchanges it, stores the grant, deletes the
+  pending file and prints `Connected to <workspace>`. A pending login lasts
+  ten minutes, and `--code` works at a terminal too.
 
 ## Commands
 
 | Command                                           | Does                                                                          |
 | ------------------------------------------------- | ----------------------------------------------------------------------------- |
 | `plot open <temp_code_…> [--agent <name>]`        | Redeem a handoff code and store the page token                                |
-| `plot login [--agent] [--site] [--no-browser]`    | Connect a workspace, approved in the browser                                  |
+| `plot login [--agent] [--no-browser]`             | Connect a workspace: sign in and approve in the browser                       |
+| `plot login --code <code>`                        | Finish a login started without a terminal, with the code the browser showed   |
 | `plot logout [<page>] [--all]`                    | Revoke a credential on the server, then forget it                             |
 | `plot whoami [<page>] [--json]`                   | What the credential acts for, its scope and expiry                            |
 | `plot pages [--limit <n>] [--next <c>] [--json]`  | Pages the workspace grant can read, newest first                              |
@@ -114,7 +138,6 @@ every other server, and refuses a file whose top level is not a JSON object.
 | ----------------- | ------------------------------------------------------------------------- |
 | `PLOT_API_URL`    | API base. Default `https://agents.plot.io`; a deployment's `.convex.site` |
 |                   | host for local dev and previews. `--api` wins over it.                    |
-| `PLOT_SITE_URL`   | Where `login` sends the browser. Default: the site the API names.         |
 | `PLOT_TOKEN`      | Use this token instead of the store (a sandbox or CI job).                |
 | `PLOT_AGENT_NAME` | Default `--agent`. Inside Claude Code the default is "Claude Code".       |
 | `XDG_CONFIG_HOME` | Where the credential store lives (below).                                 |
@@ -166,6 +189,6 @@ pnpm --filter @plotio/cli build        # dist/plot.js, one bundled file
 `pnpm publish` from a clean tree still ship `dist/plot.js`.
 
 All HTTP lives in `src/api.ts`. The build bundles with esbuild rather than
-emitting with `tsc`, because `@plot/shared` (token shapes, minting and
-hashing) is a private workspace package: the bundle inlines it, so the
+emitting with `tsc`, because `@plot/shared` (token shapes) is a private
+workspace package: the bundle inlines it, so the
 published package has no dependencies at all.

package/dist/plot.js

@@ -21,11 +21,10 @@ Run "plot --help" for usage.`, 2);
 };
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 
 // src/api.ts
 var DEFAULT_API_URL = "https://agents.plot.io";
-var DEFAULT_SITE_URL = "https://www.plot.io";
 var ApiError = class extends Error {
   status;
   /** The server's machine reason (`expired`, `no_access`, …), or `network`/`http`. */
@@ -55,10 +54,6 @@ function resolveApiBase(flag, env) {
     "API URL"
   );
 }
-function explicitSiteBase(flag, env) {
-  const raw = flag || env.PLOT_SITE_URL?.trim();
-  return raw ? normalizeBase(raw, "Site URL") : void 0;
-}
 var UPDATE_LEVELS = [
   "every",
   "substantial",
@@ -126,24 +121,80 @@ function createApi(opts) {
     /**
      * GET /.well-known/oauth-authorization-server, unauthenticated. Its
      * `authorization_endpoint` is on the web app that deployment belongs to,
-     * which is how `login` finds the site for an `--api` it was not told the
-     * site of.
+     * which is how `login` finds the site for any `--api`; its
+     * `token_endpoint` is where the code is exchanged.
      */
     async authorizationServer() {
       return json(
         await request("GET", "/.well-known/oauth-authorization-server")
       );
     },
+    /**
+     * POST <token_endpoint>: exchange an authorization code for a workspace
+     * token. A form body, as OAuth has it, and OAuth-shaped errors
+     * (`{ error, error_description }`), whose description becomes the
+     * message. Never retried: a code works once.
+     */
+    async exchangeCode(tokenEndpoint, form) {
+      const url = new URL(tokenEndpoint);
+      let response;
+      try {
+        response = await fetchFn(url, {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": `plot-cli/${VERSION}`
+          },
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            ...form
+          }).toString()
+        });
+      } catch (err) {
+        throw new ApiError(
+          0,
+          "network",
+          `Could not reach ${url.origin}: ${err.message}`
+        );
+      }
+      const text = await response.text().catch(() => "");
+      let body;
+      try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object") {
+          body = parsed;
+        }
+      } catch {
+      }
+      if (!response.ok) {
+        const code = typeof body?.error === "string" ? body.error : "http";
+        const description = typeof body?.error_description === "string" ? body.error_description : void 0;
+        throw new ApiError(
+          response.status,
+          code,
+          description ?? `The token request failed with HTTP ${response.status} (${code}).`
+        );
+      }
+      if (typeof body?.access_token !== "string" || !body.access_token) {
+        throw new ApiError(
+          response.status,
+          "bad_response",
+          `Expected an access_token from ${url.origin}, got: ${text.slice(0, 200)}`
+        );
+      }
+      return body;
+    },
     /** DELETE /v1/me: revoke the presented credential. */
     async revoke(token) {
       await request("DELETE", "/v1/me", { token });
     },
     /** GET /v1/pages: pages the workspace grant can read, newest first. */
-    async pages(token, page = {}) {
+    async pages(token, page2 = {}) {
       return json(
         await request("GET", "/v1/pages", {
           token,
-          query: { limit: page.limit, cursor: page.next }
+          query: { limit: page2.limit, cursor: page2.next }
         })
       );
     },
@@ -192,11 +243,11 @@ function createApi(opts) {
       );
     },
     /** GET /v1/search?q=. */
-    async search(token, q, page = {}) {
+    async search(token, q, page2 = {}) {
       return json(
         await request("GET", "/v1/search", {
           token,
-          query: { q, limit: page.limit, cursor: page.next }
+          query: { q, limit: page2.limit, cursor: page2.next }
         })
       );
     },
@@ -270,28 +321,10 @@ var LOOSE = new RegExp("^(?:\\p{Regional_Indicator}{2}|[0-9#*]\uFE0F?\u20E3|\\p{
 
 // ../shared/src/agentTokens.ts
 var AGENT_CODE_PREFIX = "temp_code_";
-var AGENT_SESSION_PREFIX = "plot_agent_sk_";
 var AGENT_CODE_TTL_MS = 10 * 60 * 1e3;
 var AGENT_JOIN_TOKEN_TTL_MS = 2 * 60 * 1e3;
 var AGENT_SESSION_IDLE_TTL_MS = 24 * 60 * 60 * 1e3;
 var AGENT_SESSION_MAX_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
-function base64Url(bytes) {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}
-function mintAgentToken(prefix) {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  return prefix + base64Url(bytes);
-}
-async function hashAgentToken(token) {
-  const digest = await crypto.subtle.digest(
-    "SHA-256",
-    new TextEncoder().encode(token)
-  );
-  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
 function looksLikeToken(value, prefix) {
   return typeof value === "string" && value.startsWith(prefix) && value.length > prefix.length && value.length <= prefix.length + 64;
 }
@@ -364,7 +397,8 @@ var USAGE = `plot ${VERSION}: Plot pages for agents and scripts
 Usage: plot <command> [options]
 
   open <temp_code_\u2026> [--agent <name>]   Redeem a handoff code; stores the page token
-  login [--agent <name>] [--site <url>] Connect a workspace (approve in the browser)
+  login [--agent <name>] [--no-browser] Connect a workspace (sign in in the browser)
+  login --code <code>                   Finish a login with the code the browser showed
   logout [<page>] [--all]               Revoke a credential and forget it
   whoami [<page>]                       What the stored credential can reach
   pages [--limit <n>] [--next <c>]      Pages you can read (workspace login)
@@ -390,8 +424,11 @@ date as people talk. You reach a page with a token someone gave you.
 
 Get access (once; the token is stored, so later shells need nothing):
   plot open temp_code_\u2026 --agent "<your name>"   A code a person copied from a page
-  plot login --agent "<your name>"              Or a whole workspace; a person approves
-                                                it in the browser, so show them the URL
+  plot login --agent "<your name>"              Or a whole workspace: it prints a URL
+                                                and exits. Give the person the URL;
+                                                they sign in, approve, and send you
+                                                the code the page shows. Then:
+  plot login --code <code>                      Finishes it (within ten minutes)
 
 Read:
   plot read <page>            The page as Markdown: transcript, then Topics.
@@ -425,14 +462,25 @@ Redeems a one-time handoff code (from a page's "Copy agent instructions")
 for a page token, and stores it. A code works once and lasts ten minutes.
 --agent names you in the page's share dialog (default: PLOT_AGENT_NAME,
 "Claude Code" inside Claude Code, else "Plot CLI").`,
-  login: `plot login [--agent <name>] [--site <url>] [--no-browser]
+  login: `plot login [--agent <name>] [--no-browser]
+plot login --code <code>
+
+Connects a whole workspace with OAuth (authorization code and PKCE), signing
+in on the web app the API names in its OAuth metadata (so --api at a local
+or preview deployment signs in on that deployment's own site).
 
-Connects a whole workspace. Mints a token here, opens the browser at
-<site>/connect to approve it (and prints the URL), then waits up to ten
-minutes for the approval. Type the code it prints on that page. --site
-defaults to PLOT_SITE_URL, else the site the API names (its OAuth metadata),
-so --api at a local or preview deployment approves on that deployment's own
-web app.`,
+In a terminal it opens this machine's browser, which hands the code back by
+itself, and prints a URL for a browser anywhere else (over SSH, another
+computer): approving there shows a code to paste at "Paste code here if
+prompted:". It waits up to ten minutes.
+
+Without a terminal (an agent's shell, a pipe) it prints the URL and exits.
+Whoever approves gets a code; "plot login --code <code>" finishes the login
+within ten minutes. --code works in a terminal too.
+
+--no-browser prints the URL without opening anything.
+--agent names the connection in Settings (default: PLOT_AGENT_NAME,
+"Claude Code" inside Claude Code, else "Plot CLI").`,
   logout: `plot logout [<page>] [--all]
 
 Revokes a credential (DELETE /v1/me) and forgets it. With no argument, the
@@ -500,55 +548,131 @@ there, so its block always holds the token.
 };
 
 // src/login.ts
-var LOGIN_POLL_INTERVAL_MS = 2e3;
+import { createHash, randomBytes } from "node:crypto";
+var CLIENT_ID = "plot-cli";
+var OOB_REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob";
 var LOGIN_TIMEOUT_MS = 10 * 60 * 1e3;
-function fingerprint(hash) {
-  return hash.slice(0, 6);
-}
-function buildLoginUrl(site, hash, agent) {
-  const url = new URL(`${site}/connect`);
-  url.searchParams.set("hash", hash);
-  url.searchParams.set("agent", agent);
-  url.searchParams.set("fp", fingerprint(hash));
-  return url.toString();
+var PASTE_PROMPT = "Paste code here if prompted: ";
+var PENDING_LOGIN_MS = 10 * 60 * 1e3;
+function newVerifier() {
+  return randomBytes(32).toString("base64url");
 }
-async function resolveLoginSite(opts) {
-  if (opts.explicit) return opts.explicit;
+function newState() {
+  return randomBytes(16).toString("base64url");
+}
+function challengeFor(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+async function discoverEndpoints(api, apiBase) {
   let reason;
   try {
-    const endpoint = (await opts.api.authorizationServer()).authorization_endpoint;
-    if (typeof endpoint === "string") {
-      const url = new URL(endpoint);
-      if (url.protocol === "https:" || url.protocol === "http:") {
-        return url.origin;
-      }
+    const meta = await api.authorizationServer();
+    const authorizationEndpoint = httpUrl(meta.authorization_endpoint);
+    const tokenEndpoint = httpUrl(meta.token_endpoint);
+    if (authorizationEndpoint && tokenEndpoint) {
+      return { authorizationEndpoint, tokenEndpoint };
     }
-    reason = "its OAuth metadata names no authorization endpoint";
+    reason = `its OAuth metadata names no ${authorizationEndpoint ? "token" : "authorization"} endpoint`;
   } catch (err) {
     reason = err.message;
   }
-  if (opts.apiBase === DEFAULT_API_URL) return DEFAULT_SITE_URL;
   throw new CliError(
-    `Could not tell which Plot site approves logins for ${opts.apiBase} (${reason}). Pass --site <url> (or set PLOT_SITE_URL) to the web app that deployment belongs to.`
+    `Could not start a login with ${apiBase}: ${reason}. Check --api (or PLOT_API_URL).`
   );
 }
-var FATAL = /* @__PURE__ */ new Set(["revoked", "disabled", "denied"]);
-async function waitForApproval(opts) {
-  const interval = opts.intervalMs ?? LOGIN_POLL_INTERVAL_MS;
-  const deadline = opts.now() + (opts.timeoutMs ?? LOGIN_TIMEOUT_MS);
-  for (; ; ) {
-    try {
-      return await opts.api.me(opts.token);
-    } catch (err) {
-      if (!(err instanceof ApiError)) throw err;
-      if (FATAL.has(err.code)) throw new CliError(err.message);
-    }
-    if (opts.now() + interval > deadline) {
+function httpUrl(value) {
+  if (typeof value !== "string") return void 0;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildAuthorizeUrl(opts) {
+  const url = new URL(opts.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("redirect_uri", opts.redirectUri);
+  url.searchParams.set("code_challenge", opts.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", opts.state);
+  url.searchParams.set("agent", opts.agent);
+  return url.toString();
+}
+function codeFromPaste(line, state) {
+  const text = line.trim();
+  if (/^https?:\/\//i.test(text)) {
+    const url = new URL(text);
+    const params = url.searchParams;
+    if (params.get("state") !== state) {
       throw new CliError(
-        'The login was not approved in time. Run "plot login" again.'
+        'That URL belongs to a different login. Run "plot login" again.'
       );
     }
-    await opts.sleep(interval);
+    const code = params.get("code");
+    if (!code) throw new CliError("That URL carries no code.");
+    return { code, callback: `${url.origin}${url.pathname}` };
+  }
+  return { code: text };
+}
+async function waitForCode(opts) {
+  const abort = new AbortController();
+  let timer;
+  const sources = [];
+  const loopback = opts.loopback;
+  if (loopback) {
+    sources.push(
+      loopback.code.then((code) => ({
+        code,
+        redirectUri: loopback.redirectUri
+      }))
+    );
+  }
+  if (opts.prompt) {
+    const prompt = opts.prompt;
+    sources.push(
+      (async () => {
+        for (; ; ) {
+          const line = await prompt(abort.signal);
+          if (abort.signal.aborted) return new Promise(() => {
+          });
+          if (line === void 0) {
+            if (loopback) return new Promise(() => {
+            });
+            throw new CliError(
+              'No code was pasted. Run "plot login" again, and paste the code the browser shows.'
+            );
+          }
+          if (line.trim()) {
+            const pasted = codeFromPaste(line, opts.state);
+            return {
+              code: pasted.code,
+              redirectUri: pasted.callback ? loopback?.redirectUri ?? pasted.callback : OOB_REDIRECT_URI
+            };
+          }
+        }
+      })()
+    );
+  }
+  sources.push(
+    new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(
+          new CliError(
+            'The login was not completed in time. Run "plot login" again.'
+          )
+        ),
+        opts.timeoutMs ?? LOGIN_TIMEOUT_MS
+      );
+    })
+  );
+  try {
+    return await Promise.race(sources);
+  } finally {
+    clearTimeout(timer);
+    abort.abort();
+    opts.loopback?.close();
   }
 }
 function defaultAgentName(env) {
@@ -587,15 +711,15 @@ function formatTime(value) {
   return typeof value === "string" ? value : "";
 }
 function renderPages(pages2, next) {
-  const rows = pages2.map((page) => {
+  const rows = pages2.map((page2) => {
     const extras = [
-      page.unread ? `${page.unread} unread` : "",
-      page.canPost === false ? "read-only" : ""
+      page2.unread ? `${page2.unread} unread` : "",
+      page2.canPost === false ? "read-only" : ""
     ].filter(Boolean);
-    const when = formatTime(page.updatedAt);
+    const when = formatTime(page2.updatedAt);
     return [
-      page.id,
-      page.title || "Untitled",
+      page2.id,
+      page2.title || "Untitled",
       extras.length ? `(${extras.join(", ")})` : "",
       when
     ].filter(Boolean).join("  ");
@@ -669,8 +793,8 @@ function renderUpdate(update) {
 }
 
 // src/store.ts
-import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 function credentialsPath(env, homeDir) {
   const configHome = env.XDG_CONFIG_HOME?.trim() || join(homeDir, ".config");
   return join(configHome, "plot", "credentials.json");
@@ -695,10 +819,14 @@ async function loadStore(path) {
   );
 }
 async function saveStore(path, creds, fs = nodeFs) {
+  await writePrivateJson(path, creds, fs);
+}
+async function writePrivateJson(path, value, fs = nodeFs) {
   const dir = dirname(path);
   await fs.mkdir(dir, { recursive: true, mode: 448 });
-  const tmp = join(dir, `.credentials.${process.pid}.${Date.now()}.tmp`);
-  await fs.writeFile(tmp, `${JSON.stringify(creds, null, 2)}
+  const stem = basename(path).replace(/\.json$/, "");
+  const tmp = join(dir, `.${stem}.${process.pid}.${Date.now()}.tmp`);
+  await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}
 `, {
     mode: 384
   });
@@ -716,13 +844,39 @@ async function updateStore(path, change) {
   await saveStore(path, creds);
   return creds;
 }
+function pendingLoginPath(env, homeDir) {
+  return join(dirname(credentialsPath(env, homeDir)), "pending-login.json");
+}
+async function savePendingLogin(path, pending) {
+  await writePrivateJson(path, pending);
+}
+async function loadPendingLogin(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed.api === "string" && typeof parsed.verifier === "string" && typeof parsed.state === "string" && typeof parsed.agent === "string" && typeof parsed.createdAt === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function deletePendingLogin(path) {
+  await rm(path, { force: true });
+}
 function tokenCandidates(opts) {
   if (opts.flag) return [{ token: opts.flag, source: "flag" }];
   const fromEnv = opts.env.PLOT_TOKEN?.trim();
   if (fromEnv) return [{ token: fromEnv, source: "env" }];
   const out = [];
-  const page = opts.pageId ? opts.entry?.pages?.[opts.pageId] : void 0;
-  if (page?.token) out.push({ token: page.token, source: "page" });
+  const page2 = opts.pageId ? opts.entry?.pages?.[opts.pageId] : void 0;
+  if (page2?.token) out.push({ token: page2.token, source: "page" });
   if (opts.entry?.workspace?.token) {
     out.push({ token: opts.entry.workspace.token, source: "workspace" });
   }
@@ -803,11 +957,11 @@ async function forget(rt, candidate, pageId) {
 }
 async function saveCursor(rt, pageId, cursor) {
   await updateOrigin(rt, (entry) => {
-    const page = { ...entry.pages?.[pageId], cursor };
-    if (cursor === void 0) delete page.cursor;
+    const page2 = { ...entry.pages?.[pageId], cursor };
+    if (cursor === void 0) delete page2.cursor;
     entry.pages ??= {};
-    if (Object.keys(page).length === 0) delete entry.pages[pageId];
-    else entry.pages[pageId] = page;
+    if (Object.keys(page2).length === 0) delete entry.pages[pageId];
+    else entry.pages[pageId] = page2;
   });
 }
 function needsWorkspace(err) {
@@ -867,40 +1021,114 @@ async function open(rt) {
   );
 }
 async function login(rt) {
+  if (rt.values.code !== void 0) return loginWithCode(rt);
   const agent = agentName(rt);
-  const site = await resolveLoginSite({
-    explicit: explicitSiteBase(stringFlag(rt, "site"), rt.ctx.env),
-    apiBase: rt.origin,
-    api: rt.api
+  const endpoints = await discoverEndpoints(rt.api, rt.origin);
+  const verifier = newVerifier();
+  const state = newState();
+  const authorizeUrl = (redirectUri) => buildAuthorizeUrl({
+    authorizationEndpoint: endpoints.authorizationEndpoint,
+    redirectUri,
+    challenge: challengeFor(verifier),
+    state,
+    agent
   });
-  const token = mintAgentToken(AGENT_SESSION_PREFIX);
-  const hash = await hashAgentToken(token);
-  const url = buildLoginUrl(site, hash, agent);
-  rt.ctx.err(
-    [
-      `To connect ${agent} to a Plot workspace, open this URL and approve it:`,
-      "",
-      `  ${url}`,
-      "",
-      `Type this code on the page: ${fingerprint(hash)}`,
-      "",
-      "Waiting for approval (up to 10 minutes)\u2026"
-    ].join("\n")
-  );
-  if (!rt.values["no-browser"]) await rt.ctx.openUrl(url);
-  const me = await waitForApproval({
-    api: rt.api,
-    token,
-    sleep: rt.ctx.sleep,
-    now: rt.ctx.now
+  const oobUrl = authorizeUrl(OOB_REDIRECT_URI);
+  const noBrowser = Boolean(rt.values["no-browser"]);
+  const open2 = (url) => noBrowser ? false : rt.ctx.openUrl(url).catch(() => false);
+  const intro = `To connect ${agent} to a Plot workspace, sign in and approve it in the browser.`;
+  if (!rt.ctx.stdinIsTTY) {
+    await savePendingLogin(pendingPath(rt), {
+      api: rt.origin,
+      verifier,
+      state,
+      agent,
+      createdAt: rt.ctx.now()
+    });
+    const opened = await open2(oobUrl);
+    rt.ctx.err(
+      [
+        intro,
+        urlLead(opened),
+        "",
+        `  ${oobUrl}`,
+        "",
+        `After approving, run: plot login${apiFlag(rt)} --code <code>`,
+        "The browser shows the code once you approve. It works for ten minutes."
+      ].join("\n")
+    );
+    return;
+  }
+  const loopback = noBrowser ? void 0 : await rt.ctx.listenLoopback(state);
+  let code;
+  try {
+    const opened = await open2(
+      loopback ? authorizeUrl(loopback.redirectUri) : oobUrl
+    );
+    rt.ctx.err([intro, urlLead(opened), "", `  ${oobUrl}`, ""].join("\n"));
+    code = await waitForCode({
+      loopback,
+      state,
+      timeoutMs: rt.ctx.loginTimeoutMs,
+      prompt: (signal) => rt.ctx.promptLine(PASTE_PROMPT, signal)
+    });
+  } finally {
+    loopback?.close();
+  }
+  await finishLogin(rt, endpoints.tokenEndpoint, verifier, code);
+}
+function urlLead(opened) {
+  return opened ? "A browser tab should have opened. If it did not, or it is on another machine, open this URL:" : "Open this URL to sign in:";
+}
+function apiFlag(rt) {
+  return rt.origin === DEFAULT_API_URL ? "" : ` --api ${rt.origin}`;
+}
+function pendingPath(rt) {
+  return pendingLoginPath(rt.ctx.env, rt.ctx.homeDir);
+}
+async function loginWithCode(rt) {
+  const text = typeof rt.values.code === "string" ? rt.values.code.trim() : "";
+  if (!text) {
+    throw new UsageError("--code needs the code the browser showed.");
+  }
+  const path = pendingPath(rt);
+  const pending = await loadPendingLogin(path);
+  if (!pending) {
+    throw new CliError(
+      `No login is waiting for a code. Run "plot login${apiFlag(rt)}" first, approve in the browser, then run "plot login${apiFlag(rt)} --code <code>" with the code it shows.`
+    );
+  }
+  if (pending.api !== rt.origin) {
+    throw new CliError(
+      `The login waiting for a code was started against ${pending.api}, not ${rt.origin}. Run "plot login --api ${pending.api} --code <code>", or start again with "plot login${apiFlag(rt)}".`
+    );
+  }
+  if (rt.ctx.now() - pending.createdAt > PENDING_LOGIN_MS) {
+    await deletePendingLogin(path);
+    throw new CliError(
+      `The login waiting for a code is more than ten minutes old. Run "plot login${apiFlag(rt)}" again.`
+    );
+  }
+  const pasted = codeFromPaste(text, pending.state);
+  const endpoints = await discoverEndpoints(rt.api, rt.origin);
+  await finishLogin(rt, endpoints.tokenEndpoint, pending.verifier, {
+    code: pasted.code,
+    redirectUri: OOB_REDIRECT_URI
+  });
+  await deletePendingLogin(path);
+}
+async function finishLogin(rt, tokenEndpoint, verifier, received) {
+  const token = await rt.api.exchangeCode(tokenEndpoint, {
+    code: received.code,
+    code_verifier: verifier,
+    client_id: CLIENT_ID,
+    redirect_uri: received.redirectUri
   });
+  const me = await rt.api.me(token.access_token);
   const workspace = me.workspace?.name;
+  const expiresAt = me.expiresAt !== void 0 ? formatTime(me.expiresAt) : typeof token.expires_in === "number" ? formatTime(rt.ctx.now() + token.expires_in * 1e3) : void 0;
   await updateOrigin(rt, (entry) => {
-    entry.workspace = {
-      token,
-      workspace,
-      expiresAt: me.expiresAt === void 0 ? void 0 : formatTime(me.expiresAt)
-    };
+    entry.workspace = { token: token.access_token, workspace, expiresAt };
   });
   rt.ctx.out(`Connected${workspace ? ` to ${workspace}` : ""}. Try: plot pages`);
 }
@@ -917,23 +1145,23 @@ async function logout(rt) {
         token: entry.workspace.token
       });
     }
-    for (const [id, page] of Object.entries(entry.pages ?? {})) {
-      if (page.token) {
+    for (const [id, page2] of Object.entries(entry.pages ?? {})) {
+      if (page2.token) {
         targets.push({
-          label: `page "${page.title ?? id}"`,
-          token: page.token
+          label: `page "${page2.title ?? id}"`,
+          token: page2.token
         });
       }
     }
   } else if (rt.positionals[0]) {
     const pageId = parsePageRef(rt.positionals[0]);
-    const page = entry.pages?.[pageId];
-    if (!page?.token) {
+    const page2 = entry.pages?.[pageId];
+    if (!page2?.token) {
       throw new CliError(`No stored credential for page ${pageId}.`);
     }
     targets.push({
-      label: `page "${page.title ?? pageId}"`,
-      token: page.token
+      label: `page "${page2.title ?? pageId}"`,
+      token: page2.token
     });
   } else if (entry.workspace) {
     targets.push({
@@ -967,13 +1195,13 @@ async function logout(rt) {
   }
   await updateOrigin(rt, (e) => {
     if (e.workspace && revoked.has(e.workspace.token)) delete e.workspace;
-    for (const [id, page] of Object.entries(e.pages ?? {})) {
-      if (page.token && revoked.has(page.token)) {
+    for (const [id, page2] of Object.entries(e.pages ?? {})) {
+      if (page2.token && revoked.has(page2.token)) {
         if (rt.values.all) delete e.pages[id];
         else {
-          delete page.token;
-          delete page.expiresAt;
-          if (!page.cursor) delete e.pages[id];
+          delete page2.token;
+          delete page2.expiresAt;
+          if (!page2.cursor) delete e.pages[id];
         }
       }
     }
@@ -993,20 +1221,20 @@ async function whoami(rt) {
   }
   rt.ctx.out(describeMe(me.me, me.source, rt.origin));
   const others = Object.entries(entry.pages ?? {}).filter(
-    ([id, page]) => page.token && id !== pageId
+    ([id, page2]) => page2.token && id !== pageId
   );
   if (others.length > 0 && !pageId) {
     rt.ctx.out(
       ["", "Stored page credentials:"].concat(
         others.map(
-          ([id, page]) => `  ${id}  ${page.title ?? ""}${page.expiresAt ? `  (expires ${page.expiresAt})` : ""}`
+          ([id, page2]) => `  ${id}  ${page2.title ?? ""}${page2.expiresAt ? `  (expires ${page2.expiresAt})` : ""}`
         )
       ).join("\n")
     );
   }
 }
 function describeMe(me, source, origin) {
-  const page = me.page ? `${me.page.title || "Untitled"} (${me.page.id})${me.page.canPost === false ? ", read-only" : me.page.canPost ? ", can post" : ""}` : void 0;
+  const page2 = me.page ? `${me.page.title || "Untitled"} (${me.page.id})${me.page.canPost === false ? ", read-only" : me.page.canPost ? ", can post" : ""}` : void 0;
   const time = (value) => value === void 0 || value === null ? void 0 : formatTime(value);
   const rows = [
     ["API", origin],
@@ -1014,7 +1242,7 @@ function describeMe(me, source, origin) {
     ["Agent", me.agent],
     ["Granted by", me.grantedBy],
     ["Workspace", me.workspace?.name],
-    ["Page", page],
+    ["Page", page2],
     ["Connected", time(me.connectedAt)],
     ["Last used", time(me.lastUsedAt)],
     ["Expires", time(me.expiresAt)],
@@ -1356,8 +1584,8 @@ var COMMANDS = {
     run: login,
     options: {
       agent: { type: "string" },
-      site: { type: "string" },
-      "no-browser": { type: "boolean" }
+      "no-browser": { type: "boolean" },
+      code: { type: "string" }
     }
   },
   logout: { run: logout, options: { all: { type: "boolean" } } },
@@ -1452,6 +1680,107 @@ async function run(argv, ctx) {
 // src/context.ts
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+// src/loopback.ts
+import { createServer } from "node:http";
+function startLoopback(state) {
+  let resolveCode;
+  let rejectCode;
+  const code = new Promise((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+  code.catch(() => {
+  });
+  let done = false;
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/callback") {
+      return page(res, 404, "Not found", "Nothing here.");
+    }
+    const params = url.searchParams;
+    if (done) {
+      return page(
+        res,
+        409,
+        "Already finished",
+        "This login has already finished. Return to the terminal."
+      );
+    }
+    if (params.get("state") !== state) {
+      return page(
+        res,
+        400,
+        "Not this login",
+        'This sign-in does not belong to the login waiting in the terminal, so it was ignored. Run "plot login" again if you meant to connect.'
+      );
+    }
+    const error = params.get("error");
+    if (error) {
+      done = true;
+      const failure = oauthFailure(error, params.get("error_description"));
+      page(res, 403, "Plot was not connected", failure.message);
+      rejectCode(failure);
+      return;
+    }
+    const value = params.get("code");
+    if (!value) {
+      return page(res, 400, "No code", "The callback carried no code.");
+    }
+    done = true;
+    page(
+      res,
+      200,
+      "Plot is connected",
+      "You can close this tab and return to the terminal."
+    );
+    resolveCode(value);
+  });
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      const { port } = server.address();
+      let closed = false;
+      resolve({
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        code,
+        close: () => {
+          if (closed) return;
+          closed = true;
+          server.close();
+          server.closeIdleConnections();
+          setTimeout(() => server.closeAllConnections(), 500).unref();
+        }
+      });
+    });
+  });
+}
+function oauthFailure(error, description) {
+  if (description) return new CliError(`Login failed: ${description}`);
+  if (error === "access_denied") {
+    return new CliError("Login failed: access was denied in the browser.");
+  }
+  return new CliError(`Login failed: the browser returned "${error}".`);
+}
+function page(res, status, title, message) {
+  const body = `<!doctype html><meta charset="utf-8"><title>${escape(title)}</title><body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem"><h1 style="font-size:1.25rem">${escape(title)}</h1><p>${escape(message)}</p></body>`;
+  res.writeHead(status, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+    Connection: "close"
+  });
+  res.end(body);
+}
+function escape(text) {
+  return text.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]
+  );
+}
+
+// src/context.ts
 function nodeContext() {
   return {
     env: process.env,
@@ -1469,10 +1798,41 @@ function nodeContext() {
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     now: () => Date.now(),
     openUrl: (url) => openInBrowser(url, process.platform),
+    listenLoopback: (state) => startLoopback(state).catch(() => void 0),
+    promptLine: (question, signal) => promptLine(question, signal),
+    loginTimeoutMs: LOGIN_TIMEOUT_MS,
     cwd: process.cwd(),
     homeDir: homedir()
   };
 }
+function promptLine(question, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve(void 0);
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: Boolean(process.stdin.isTTY)
+    });
+    let answered = false;
+    rl.once("close", () => {
+      if (!answered) resolve(void 0);
+    });
+    signal.addEventListener(
+      "abort",
+      () => {
+        if (answered) return;
+        rl.close();
+        process.stderr.write("\n");
+      },
+      { once: true }
+    );
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
 function openInBrowser(url, platform) {
   const command = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : null;
   if (!command) return Promise.resolve(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plotio/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Read Plot pages, follow a meeting as it happens, and post back, from any agent with a shell.",
   "type": "module",
   "license": "MIT",