alexandr 0.2.2 → 0.3.1

package/src/consent.js

@@ -0,0 +1,272 @@
+// THE consent ceremony — one implementation, two callers.
+//
+// Extracted from link.js 2026-09-05 (app-system-stage-1.md §2 WP-E). It was
+// written for `alexandr link` (bind this box to an account) and is now also what
+// `alexandr app link` runs, asking for a different SCOPE. Copying it would have
+// meant two ceremonies drifting apart on the security-critical half of the CLI,
+// so it moved here and grew one parameter.
+//
+// Two grant shapes, one ceremony:
+//   - DEVICE (RFC 8628 shape) on a headless machine: the CLI mints a grant,
+//     prints a short code + URL, and polls until a signed-in owner confirms from
+//     ANY device. No tunnel.
+//   - LOOPBACK (OAuth authorization-code + PKCE) on a desktop: the browser and
+//     the CLI share a machine, so the redirect lands instantly.
+//
+// SCOPE (WP-E). The CLI asks at the START and the owner sees it on the consent
+// card; the CP records it on the grant and reads it back at redeem, never from
+// the token request — a PKCE verifier (or a device code) proves possession, not
+// authorization.
+//
+//   (omitted)   -> client "cli-link", 10 minutes. `alexandr link` uses it once.
+//   "app-dev"   -> client "cli", 30 days sliding. `alexandr app link` keeps it.
+//
+// Zero dependencies. Plain Node, like the rest of this CLI.
+
+import http from "node:http";
+import os from "node:os";
+import crypto from "node:crypto";
+import readline from "node:readline";
+import { log, dim, bold, cyan, fail, step, sleep, openURL } from "./util.js";
+
+const b64url = (buf) => buf.toString("base64url");
+
+// The hosted control plane + the WEBSITE (the one web property — the web app
+// retired, website-account-surface.md). Override for dev (e.g.
+// http://localhost:47400 + http://localhost:47300) via env. The link-consent
+// page (/cli-auth) is a website surface.
+export const CP_URL = (process.env.ALEXANDR_CP_URL || "https://api.alexandr.so").replace(/\/+$/, "");
+export const APP_URL = (process.env.ALEXANDR_APP_URL || "https://alexandr.so").replace(/\/+$/, "");
+export const TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run the ceremony this machine can actually complete and return the session it
+ * earned: `{ token, expiresAt, client, scope }` (older control planes answer
+ * with `token` alone, so read the rest defensively).
+ *
+ * Throws on any break in the chain — the caller decides between `fail()` and a
+ * soft skip.
+ */
+export async function consentSession({ host, name, intent = "link", scope, domain } = {}) {
+  return useDeviceFlow()
+    ? deviceGrantSession({ host, name, intent, scope })
+    : loopbackGrantSession({ host, name, intent, scope, domain });
+}
+
+/** The DESKTOP grant — authorization-code + PKCE against a loopback redirect. */
+export async function loopbackGrantSession({ host, name, intent, scope, domain }) {
+  const verifier = b64url(crypto.randomBytes(32));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+  const state = b64url(crypto.randomBytes(16));
+
+  const { port, done } = await startLoopback();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authUrl =
+    `${APP_URL}/cli-auth?` +
+    new URLSearchParams({
+      redirect_uri: redirectUri,
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      host: host ?? "",
+      name: name ?? "",
+      // ⚠ The consent page relays this into POST /cli-auth/authorize. WITHOUT it
+      // every PKCE `app-dev` link silently gets the 10-minute session instead.
+      ...(scope ? { scope } : {}),
+      // Copy-only hint for the consent card ("refresh" renews the image
+      // credential and registers nothing) — the grant's power is identical.
+      ...(intent && intent !== "link" ? { intent } : {}),
+    }).toString();
+
+  await presentAuthUrl(authUrl, { port, domain });
+
+  const cb = await done;
+  if (cb.state !== state) throw new Error("state mismatch (possible interception).");
+
+  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
+    code: cb.code,
+    codeVerifier: verifier,
+    redirectUri,
+  });
+  if (!tok.data?.token) {
+    throw new Error(
+      `could not exchange the authorization code (${tok.error ?? "malformed response"}).`,
+    );
+  }
+  return tok.data;
+}
+
+/**
+ * The HEADLESS ceremony — the device-authorization flow, because a remote box
+ * can't receive a loopback redirect and making the user build an ssh tunnel for
+ * a sign-in was backwards. Network blips just keep polling; a real rejection
+ * throws.
+ */
+export async function deviceGrantSession({ host, name, intent, scope }) {
+  const mint = await postJson(`${CP_URL}/cli-auth/device`, { host, name, intent, scope });
+  if (!mint.data?.deviceCode || !mint.data?.userCode) {
+    throw new Error(`couldn't start the sign-in (${mint.error ?? "malformed response"}).`);
+  }
+  const { deviceCode, userCode, expiresIn = 600, interval = 3 } = mint.data;
+  log("");
+  step("Open this link on any device — your computer or your phone — and confirm the code:");
+  log(`     ${cyan(`${APP_URL}/cli-auth?code=${encodeURIComponent(userCode)}`)}`);
+  log("");
+  log(`     Code:  ${bold(userCode)}`);
+  log("");
+  log(dim(`  (waiting for the confirmation — ${Math.round(expiresIn / 60)} minutes; this updates by itself)`));
+  const deadline = Date.now() + expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    const res = await postJson(`${CP_URL}/cli-auth/device/token`, { deviceCode });
+    if (res.data?.token) return res.data;
+    if (res.data?.status === "pending") continue;
+    if (res.error?.startsWith("HTTP")) throw new Error(`the sign-in was rejected (${res.error}).`);
+    // Network blip — keep polling until the code's own deadline.
+  }
+  throw new Error("the code expired before it was confirmed — run the command again.");
+}
+
+/** Which ceremony fits this machine. ALEXANDR_DEVICE_FLOW=1|0 overrides. */
+export function useDeviceFlow() {
+  if (process.env.ALEXANDR_DEVICE_FLOW === "1") return true;
+  if (process.env.ALEXANDR_DEVICE_FLOW === "0") return false;
+  return isHeadless();
+}
+
+/** No local browser to open — a Linux box with no display server. Pure for tests. */
+export function isHeadless(platform = process.platform, env = process.env) {
+  return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+
+/**
+ * Present the consent URL honestly, by what this machine can actually do:
+ *  - HEADLESS (a server): never pretend a browser opened. Numbered steps, tunnel
+ *    FIRST (the redirect lands on the desktop's loopback and must reach this box).
+ *  - DESKTOP + TTY: ask before taking over the browser — the URL is printed
+ *    either way, so "open it yourself" is always available.
+ *  - DESKTOP non-TTY (scripts): print + best-effort open, nothing blocks.
+ */
+export async function presentAuthUrl(authUrl, { port, domain, headless = isHeadless() }) {
+  const sshTarget = `${process.env.USER || "root"}@${domain || os.hostname()}`;
+  if (headless) {
+    log("");
+    step("This machine has no browser — finish the sign-in from your computer:");
+    log(`  1. Forward the callback port ${dim("(keep this running until you're done)")}:`);
+    log(`       ${bold(`ssh -L ${port}:127.0.0.1:${port} ${sshTarget}`)}`);
+    log(`  2. Open this link in a browser signed in to your alexandr account:`);
+    log(`       ${cyan(authUrl)}`);
+    log(dim(`  (waiting for the confirmation — ${TIMEOUT_MS / 60000} minutes)`));
+    return;
+  }
+  log(dim(authUrl));
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    await new Promise((resolve) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(
+        `${cyan("›")} Press Enter to open your browser and confirm ${dim("(or open the link above yourself)")} `,
+        () => {
+          rl.close();
+          resolve();
+        },
+      );
+    });
+  }
+  openURL(authUrl);
+}
+
+/** Start a loopback listener for the OAuth redirect. Resolves {code,state} when /callback is hit. */
+export function startLoopback() {
+  let resolveFn, rejectFn;
+  const done = new Promise((res, rej) => {
+    resolveFn = res;
+    rejectFn = rej;
+  });
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://127.0.0.1");
+    // Reachability probe for the consent page: /cli-auth pings this before the
+    // user clicks, so a missing ssh tunnel becomes a guided notice instead of a
+    // dead browser error page after the click. The PNA header answers Chrome's
+    // public->loopback preflight; ACAO lets the page read the success.
+    if (u.pathname === "/ping") {
+      res.writeHead(204, {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": "GET, OPTIONS",
+        "access-control-allow-headers": "*",
+        "access-control-allow-private-network": "true",
+      });
+      res.end();
+      return;
+    }
+    if (u.pathname !== "/callback") {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(
+      "<!doctype html><meta charset=utf-8><body style='font:16px system-ui;padding:3rem;text-align:center'>Linked — you can close this tab and return to your terminal.</body>",
+    );
+    clearTimeout(timer);
+    setTimeout(() => server.close(), 200);
+    const code = u.searchParams.get("code");
+    const st = u.searchParams.get("state");
+    if (code && st) resolveFn({ code, state: st });
+    else rejectFn(new Error("no authorization code in the redirect"));
+  });
+  const timer = setTimeout(() => {
+    server.close();
+    rejectFn(new Error("timed out waiting for the browser confirmation"));
+  }, TIMEOUT_MS);
+  return new Promise((ready, readyErr) => {
+    server.once("error", (e) => {
+      rejectFn(e);
+      readyErr(e);
+    });
+    server.listen(0, "127.0.0.1", () => ready({ port: server.address().port, done }));
+  });
+}
+
+/**
+ * POST json -> `{ data }` on success, `{ error }` on failure. The CP writes
+ * human-readable `error` strings (e.g. the closed-alpha 403 explains exactly who
+ * may register), so failures must carry WHY — a bare null renders as "could not
+ * register this runtime" with the real reason swallowed. Callers surface
+ * `error` in their fail/skip message.
+ */
+export async function postJson(url, body, headers = {}) {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
+      return { error: `HTTP ${res.status}${detail}` };
+    }
+    return data == null ? { error: "malformed response" } : { data };
+  } catch (e) {
+    return { error: `couldn't reach ${new URL(url).origin}: ${e?.message ?? e}` };
+  }
+}
+
+/** GET json -> `{ data }` / `{ error }`, the read half of postJson. */
+export async function getJson(url, headers = {}) {
+  try {
+    const res = await fetch(url, { headers });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
+      return { error: `HTTP ${res.status}${detail}`, status: res.status };
+    }
+    return data == null ? { error: "malformed response" } : { data };
+  } catch (e) {
+    return { error: `couldn't reach ${new URL(url).origin}: ${e?.message ?? e}` };
+  }
+}
+
+// `fail` is re-exported so callers that want the process-exiting form don't have
+// to import two modules for one ceremony.
+export { fail };

package/src/deps.js

@@ -2,8 +2,7 @@
 // LINUX box (the self-host case), it offers to install them right there — Docker's official
 // convenience script (get.docker.com) + systemd start — instead of failing with a doc link.
 // Interactive-only (a real TTY, an explicit yes), root or sudo. macOS/Windows stay
-// guidance-only: Docker Desktop can't be installed silently, and the product's Mac story
-// ("On this Mac") uses the desktop app's own VM, never Docker.
+// guidance-only: Docker Desktop can't be installed silently.
 
 import { spawnSync } from "node:child_process";
 import { log, ok, warn, step, dim, bold } from "./util.js";

package/src/instance.js

@@ -24,7 +24,12 @@ export function resolveInstance(flags = {}) {
   const cwdProject = path.resolve(process.cwd(), "alexandr");
   if (flags.dir) {
     const dir = path.resolve(String(flags.dir));
-    return { dir, mode: "project", name: path.basename(dir), projectName: `alexandr-${sha8(dir)}` };
+    // `--project` pins the compose project NAME beside `--dir`: the updater sidecar runs the
+    // recipe from inside a container where the instance dir is mounted at its host path, and
+    // the project it must drive is the one the host created — a name re-derived in there
+    // (a global instance's is not the dir hash) would make compose start a SECOND copy.
+    const pinned = typeof flags.project === "string" && flags.project.trim() ? flags.project.trim() : null;
+    return { dir, mode: "project", name: path.basename(dir), projectName: pinned ?? `alexandr-${sha8(dir)}` };
   }
   if (fs.existsSync(path.join(cwdProject, "docker-compose.yml"))) {
     return { dir: cwdProject, mode: "project", name: path.basename(path.dirname(cwdProject)), projectName: `alexandr-${sha8(cwdProject)}` };
@@ -95,6 +100,34 @@ export function unsetEnv(dir, key) {
 }
 
 // The loopback kernel port for this instance (host side), honoring the .env.
+/**
+ * Keep the newest `keep` pre-update snapshots in `<dir>/backups` and delete the rest
+ * (owner, 2026-09-08: keep 3). Every update — the terminal verb and the sidecar's button —
+ * snapshots /data first, and a box that is updated often would otherwise fill its disk with
+ * tarballs nobody will restore. Returns the paths removed. Only `pre-update-*.tgz` is touched:
+ * a snapshot the operator took with `alexandr backup` is theirs to keep.
+ */
+export function pruneSnapshots(dir, keep = 3) {
+  const backups = path.join(dir, "backups");
+  if (!fs.existsSync(backups)) return [];
+  const snaps = fs
+    .readdirSync(backups)
+    .filter((f) => /^pre-update-.*\.tgz$/.test(f))
+    .map((f) => ({ f, at: fs.statSync(path.join(backups, f)).mtimeMs }))
+    .sort((a, b) => b.at - a.at);
+  const removed = [];
+  for (const { f } of snaps.slice(Math.max(0, keep))) {
+    const p = path.join(backups, f);
+    try {
+      fs.unlinkSync(p);
+      removed.push(p);
+    } catch {
+      /* a snapshot that will not go is not worth failing an update over */
+    }
+  }
+  return removed;
+}
+
 export function kernelPort(dir) {
   const v = readEnv(dir).ALEXANDR_KERNEL_PORT;
   const n = v ? Number(v) : 3030;

package/src/link.js

@@ -10,22 +10,19 @@
 // step one (an unlinked box refuses to serve), and `alexandr link` remains the explicit
 // re-link/repair verb.
 
-import http from "node:http";
-import os from "node:os";
-import crypto from "node:crypto";
-import readline from "node:readline";
-import { log, dim, bold, cyan, fail, step, ok, warn, openURL, sleep } from "./util.js";
+import { log, dim, fail, step, ok, warn } from "./util.js";
 import { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv, unsetEnv } from "./instance.js";
 import { kernelUrl, health, waitPosture } from "./probe.js";
 import { compose, exec } from "./docker.js";
+// ⚠ THE CEREMONY MOVED to ./consent.js 2026-09-05 (app-system-stage-1.md §2 WP-E)
+// so `alexandr app link` could run the same one with a different SCOPE. Copying
+// it would have left two drifting implementations of the security-critical half
+// of this CLI. Nothing about the verbs below changed: they ask for no scope, so
+// they still get today's 10-minute `cli-link` session.
+import { APP_URL, CP_URL, consentSession, isHeadless, postJson, presentAuthUrl, startLoopback } from "./consent.js";
 
-const b64url = (buf) => buf.toString("base64url");
-// Default to the hosted control plane + the WEBSITE (the one web property — the web app retired,
-// website-account-surface.md); override for dev (e.g. http://localhost:4000 + http://localhost:3000)
-// via env. The link-consent page (/cli-auth) + the account page are website surfaces now.
-const CP_URL = (process.env.ALEXANDR_CP_URL || "https://api.alexandr.so").replace(/\/+$/, "");
-const APP_URL = (process.env.ALEXANDR_APP_URL || "https://alexandr.so").replace(/\/+$/, "");
-const TIMEOUT_MS = 5 * 60 * 1000;
+// Re-exported: these were this module's public surface before the extraction.
+export { isHeadless, presentAuthUrl, startLoopback };
 
 /** Whether this instance's .env already carries the connected credential trio. */
 export function isLinked(dir) {
@@ -103,14 +100,11 @@ export async function runLinkCeremony(inst, flags) {
 
   step(`Link ${boxUrl} to your alexandr account`);
   let sessionToken;
-  if (useDeviceFlow()) {
-    try {
-      sessionToken = await deviceGrantToken(boxUrl, name, "link");
-    } catch (e) {
-      fail(`Link aborted: ${e.message}`);
-    }
-  } else {
-    sessionToken = await loopbackGrantToken({ boxUrl, name, domain });
+  try {
+    // No scope: this ceremony wants today's short single-use `cli-link` session.
+    sessionToken = (await consentSession({ host: boxUrl, name, intent: "link", domain })).token;
+  } catch (e) {
+    fail(`Link aborted: ${e.message}`);
   }
   await registerAndPersist(inst, { boxUrl, name, sessionToken });
 }
@@ -126,93 +120,6 @@ function instanceCoords(inst, flags) {
   return { domain, boxUrl };
 }
 
-/** The DESKTOP grant — OAuth authorization-code + PKCE against a loopback redirect the
- *  browser on THIS machine can reach. Returns the short-lived session token. */
-async function loopbackGrantToken({ boxUrl, name, domain, intent }) {
-  // PKCE (S256) + a CSRF state for the loopback redirect.
-  const verifier = b64url(crypto.randomBytes(32));
-  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
-  const state = b64url(crypto.randomBytes(16));
-
-  const { port, done } = await startLoopback();
-  const redirectUri = `http://127.0.0.1:${port}/callback`;
-  const authUrl =
-    `${APP_URL}/cli-auth?` +
-    new URLSearchParams({
-      redirect_uri: redirectUri,
-      state,
-      code_challenge: challenge,
-      code_challenge_method: "S256",
-      host: boxUrl,
-      name,
-      // Copy-only hint for the consent card ("refresh" renews the image credential and
-      // registers nothing) — the grant's power is identical either way.
-      ...(intent && intent !== "link" ? { intent } : {}),
-    }).toString();
-
-  await presentAuthUrl(authUrl, { port, domain });
-
-  let cb;
-  try {
-    cb = await done;
-  } catch (e) {
-    fail(`Link aborted: ${e.message}`);
-  }
-  if (cb.state !== state) fail("Link aborted: state mismatch (possible interception).");
-
-  // Exchange the code (+ PKCE verifier) for a short-lived session, then register this runtime.
-  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
-    code: cb.code,
-    codeVerifier: verifier,
-    redirectUri,
-  });
-  if (!tok.data?.token) {
-    fail(`Link failed: could not exchange the authorization code (${tok.error ?? "malformed response"}).`);
-  }
-  return tok.data.token;
-}
-
-/**
- * The HEADLESS ceremony — the device-authorization flow (RFC 8628 shape), because a remote
- * box can't receive a loopback redirect and making the user build an ssh tunnel for a
- * sign-in was backwards. The CLI mints a grant, shows a short code + URL (any browser on
- * any device), and polls until the signed-in owner confirms. Throws on fatal (the caller
- * decides between fail() and best-effort skip); network blips just keep polling.
- */
-async function deviceGrantToken(host, name, intent) {
-  const mint = await postJson(`${CP_URL}/cli-auth/device`, { host, name, intent });
-  if (!mint.data?.deviceCode || !mint.data?.userCode) {
-    throw new Error(`couldn't start the sign-in (${mint.error ?? "malformed response"}).`);
-  }
-  const { deviceCode, userCode, expiresIn = 600, interval = 3 } = mint.data;
-  log("");
-  step("Open this link on any device — your computer or your phone — and confirm the code:");
-  log(`     ${cyan(`${APP_URL}/cli-auth?code=${encodeURIComponent(userCode)}`)}`);
-  log("");
-  log(`     Code:  ${bold(userCode)}`);
-  log("");
-  log(dim(`  (waiting for the confirmation — ${Math.round(expiresIn / 60)} minutes; this updates by itself)`));
-  const deadline = Date.now() + expiresIn * 1000;
-  while (Date.now() < deadline) {
-    await sleep(interval * 1000);
-    const res = await postJson(`${CP_URL}/cli-auth/device/token`, { deviceCode });
-    if (res.data?.token) return res.data.token;
-    if (res.data?.status === "pending") continue;
-    if (res.error?.startsWith("HTTP")) throw new Error(`the sign-in was rejected (${res.error}).`);
-    // Network blip — keep polling until the code's own deadline.
-  }
-  throw new Error("the code expired before it was confirmed — run the command again.");
-}
-
-/** Which ceremony fits this machine: the device flow wherever a local browser can't
- *  receive the redirect (headless servers), the instant loopback redirect elsewhere.
- *  ALEXANDR_DEVICE_FLOW=1|0 overrides either way. */
-function useDeviceFlow() {
-  if (process.env.ALEXANDR_DEVICE_FLOW === "1") return true;
-  if (process.env.ALEXANDR_DEVICE_FLOW === "0") return false;
-  return isHeadless();
-}
-
 /** Register the runtime with a freshly-granted session and persist the credential trio. */
 async function registerAndPersist(inst, { boxUrl, name, sessionToken }) {
   const reg = await postJson(
@@ -310,9 +217,7 @@ export async function refreshRegistryLogin(inst, flags) {
   const { domain, boxUrl } = instanceCoords(inst, flags);
   const name = (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() || "Self-hosted runtime";
   step("Sign in to refresh this runtime's image credential…");
-  const token = useDeviceFlow()
-    ? await deviceGrantToken(boxUrl, name, "refresh")
-    : await loopbackGrantToken({ boxUrl, name, domain, intent: "refresh" });
+  const { token } = await consentSession({ host: boxUrl, name, intent: "refresh", domain });
   return (await registryLogin(token)) === "done";
 }
 
@@ -329,62 +234,23 @@ export async function unlinkFromAccount(inst, flags) {
     return false;
   }
   step("Sign in to remove this runtime from your account…");
-  if (useDeviceFlow()) {
-    let token;
-    try {
-      token = await deviceGrantToken(kernelUrl(kernelPort(inst.dir)), "Unlink this runtime", "unlink");
-    } catch (e) {
-      log(dim(`  (unlink skipped: ${e.message})`));
-      return false;
-    }
-    try {
-      const res = await fetch(`${CP_URL}/instances/${encodeURIComponent(workspaceId)}`, {
-        method: "DELETE",
-        headers: { authorization: `Bearer ${token}` },
-      });
-      if (res.ok) scrubCredentials(inst.dir);
-      return res.ok;
-    } catch {
-      return false;
-    }
-  }
-  const verifier = b64url(crypto.randomBytes(32));
-  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
-  const state = b64url(crypto.randomBytes(16));
-  const { port, done } = await startLoopback();
-  const redirectUri = `http://127.0.0.1:${port}/callback`;
-  const authUrl =
-    `${APP_URL}/cli-auth?` +
-    new URLSearchParams({
-      redirect_uri: redirectUri,
-      state,
-      code_challenge: challenge,
-      code_challenge_method: "S256",
+  let token;
+  try {
+    // No scope — a one-shot `cli-link` session is exactly what a DELETE needs.
+    ({ token } = await consentSession({
       host: kernelUrl(kernelPort(inst.dir)),
       name: "Unlink this runtime",
-    }).toString();
-  await presentAuthUrl(authUrl, { port, domain: (env.ALEXANDR_DOMAIN || "").trim() || undefined });
-  let cb;
-  try {
-    cb = await done;
+      intent: "unlink",
+      domain: (env.ALEXANDR_DOMAIN || "").trim() || undefined,
+    }));
   } catch (e) {
     log(dim(`  (unlink skipped: ${e.message})`));
     return false;
   }
-  if (cb.state !== state) return false;
-  const tok = await postJson(`${CP_URL}/cli-auth/token`, {
-    code: cb.code,
-    codeVerifier: verifier,
-    redirectUri,
-  });
-  if (!tok.data?.token) {
-    log(dim(`  (unlink skipped: ${tok.error ?? "malformed response"})`));
-    return false;
-  }
   try {
     const res = await fetch(`${CP_URL}/instances/${encodeURIComponent(workspaceId)}`, {
       method: "DELETE",
-      headers: { authorization: `Bearer ${tok.data.token}` },
+      headers: { authorization: `Bearer ${token}` },
     });
     if (res.ok) scrubCredentials(inst.dir);
     return res.ok;
@@ -402,119 +268,6 @@ function scrubCredentials(dir) {
   unsetEnv(dir, "ALEXANDR_WORKSPACE_ID");
 }
 
-/** No local browser to open — a Linux box with no display server. The PRIMARY self-host
- *  case, so it must be first-class, not a dim afterthought. Pure for tests. */
-export function isHeadless(platform = process.platform, env = process.env) {
-  return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY;
-}
-
-/**
- * Present the consent URL honestly, by what this machine can actually do:
- *  - HEADLESS (a server): never pretend a browser opened. Numbered steps, tunnel FIRST
- *    (the redirect lands on the desktop's loopback and must reach this box), URL bright.
- *  - DESKTOP + TTY: ask before taking over the browser — the URL is printed either way,
- *    so "open it yourself" is always available.
- *  - DESKTOP non-TTY (scripts): old behavior — print + best-effort open, nothing blocks.
- */
-export async function presentAuthUrl(authUrl, { port, domain, headless = isHeadless() }) {
-  const sshTarget = `${process.env.USER || "root"}@${domain || os.hostname()}`;
-  if (headless) {
-    log("");
-    step("This machine has no browser — finish the sign-in from your computer:");
-    log(`  1. Forward the callback port ${dim("(keep this running until you're done)")}:`);
-    log(`       ${bold(`ssh -L ${port}:127.0.0.1:${port} ${sshTarget}`)}`);
-    log(`  2. Open this link in a browser signed in to your alexandr account:`);
-    log(`       ${cyan(authUrl)}`);
-    log(dim(`  (waiting for the confirmation — ${TIMEOUT_MS / 60000} minutes)`));
-    return;
-  }
-  log(dim(authUrl));
-  if (process.stdin.isTTY && process.stdout.isTTY) {
-    await new Promise((resolve) => {
-      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-      rl.question(`${cyan("›")} Press Enter to open your browser and confirm ${dim("(or open the link above yourself)")} `, () => {
-        rl.close();
-        resolve();
-      });
-    });
-  }
-  openURL(authUrl);
-}
-
-/** Start a loopback listener for the OAuth redirect. Resolves {code,state} when /callback is hit. */
-export function startLoopback() {
-  let resolveFn, rejectFn;
-  const done = new Promise((res, rej) => {
-    resolveFn = res;
-    rejectFn = rej;
-  });
-  const server = http.createServer((req, res) => {
-    const u = new URL(req.url, "http://127.0.0.1");
-    // Reachability probe for the consent page: /cli-auth pings this before the user
-    // clicks Link, so a missing ssh tunnel becomes a guided "start the tunnel" notice
-    // instead of a dead browser error page after the click. The PNA header answers
-    // Chrome's public→loopback preflight; ACAO lets the page read the success.
-    if (u.pathname === "/ping") {
-      res.writeHead(204, {
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, OPTIONS",
-        "access-control-allow-headers": "*",
-        "access-control-allow-private-network": "true",
-      });
-      res.end();
-      return;
-    }
-    if (u.pathname !== "/callback") {
-      res.writeHead(404);
-      res.end();
-      return;
-    }
-    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
-    res.end(
-      "<!doctype html><meta charset=utf-8><body style='font:16px system-ui;padding:3rem;text-align:center'>Linked — you can close this tab and return to your terminal.</body>",
-    );
-    clearTimeout(timer);
-    setTimeout(() => server.close(), 200);
-    const code = u.searchParams.get("code");
-    const st = u.searchParams.get("state");
-    if (code && st) resolveFn({ code, state: st });
-    else rejectFn(new Error("no authorization code in the redirect"));
-  });
-  const timer = setTimeout(() => {
-    server.close();
-    rejectFn(new Error("timed out waiting for the browser confirmation"));
-  }, TIMEOUT_MS);
-  return new Promise((ready, readyErr) => {
-    server.once("error", (e) => {
-      rejectFn(e);
-      readyErr(e);
-    });
-    server.listen(0, "127.0.0.1", () => ready({ port: server.address().port, done }));
-  });
-}
-
-/** POST json → `{ data }` on success, `{ error }` on failure. The CP writes human-readable
- *  `error` strings (e.g. the closed-alpha 403 explains exactly who may register), so failures
- *  must carry WHY — a bare null renders as "could not register this runtime" with the real
- *  reason swallowed. Callers surface `error` in their fail/skip message. */
-async function postJson(url, body, headers = {}) {
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...headers },
-      body: JSON.stringify(body),
-    });
-    const data = await res.json().catch(() => null);
-    if (!res.ok) {
-      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
-      return { error: `HTTP ${res.status}${detail}` };
-    }
-    return data == null ? { error: "malformed response" } : { data };
-  } catch (e) {
-    return { error: `couldn't reach ${new URL(url).origin}: ${e?.message ?? e}` };
-  }
-}
-
 async function isRunning(dir) {
   try {
     return !!(await health(kernelUrl(kernelPort(dir))));