alexandr 0.2.1 → 0.3.0

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 { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv } from "./instance.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) {
@@ -95,13 +92,7 @@ export async function link(flags) {
  *  Two grant shapes, one registration: the DEVICE flow on headless machines (a short code
  *  confirmed from any browser — no tunnel), the instant loopback PKCE redirect on desktops. */
 export async function runLinkCeremony(inst, flags) {
-  // The URL the CP records + the SSO handoff redirects back to. --domain (or a domain already in
-  // .env) for a publicly-reachable box; otherwise the loopback kernel URL (fine for a box you open
-  // locally — and the runtime self-reports its origin on heartbeat either way).
-  const domain = flags.domain || readEnv(inst.dir).ALEXANDR_DOMAIN;
-  const boxUrl = domain
-    ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
-    : kernelUrl(kernelPort(inst.dir));
+  const { domain, boxUrl } = instanceCoords(inst, flags);
   const name =
     (typeof flags.name === "string" && flags.name.trim()) ||
     (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() ||
@@ -109,100 +100,24 @@ 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 });
-  }
-  await registerAndPersist(inst, { boxUrl, name, sessionToken });
-}
-
-/** 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 }) {
-  // 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,
-    }).toString();
-
-  await presentAuthUrl(authUrl, { port, domain });
-
-  let cb;
   try {
-    cb = await done;
+    // 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}`);
   }
-  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.");
+  await registerAndPersist(inst, { boxUrl, name, sessionToken });
 }
 
-/** 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();
+/** The URL the CP records + the consent card names. --domain (or a domain already in .env)
+ *  for a publicly-reachable box; otherwise the loopback kernel URL (fine for a box you open
+ *  locally — and the runtime self-reports its origin on heartbeat either way). */
+function instanceCoords(inst, flags) {
+  const domain = flags.domain || readEnv(inst.dir).ALEXANDR_DOMAIN;
+  const boxUrl = domain
+    ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
+    : kernelUrl(kernelPort(inst.dir));
+  return { domain, boxUrl };
 }
 
 /** Register the runtime with a freshly-granted session and persist the credential trio. */
@@ -264,25 +179,46 @@ async function registryLogin(sessionToken) {
     warn(
       `The control plane couldn't provide the runtime-image credential (${r.error ?? "malformed response"}) — the image pull will fail. Retry later, or contact your operator.`,
     );
-    return;
+    return "none";
   }
   pendingPullCred = r.data;
-  applyRegistryLogin();
+  return applyRegistryLogin();
 }
 
-/** Run the held `docker login` if the docker CLI is available; no-op otherwise (the caller
- *  re-invokes after installing dependencies). Exported for `up`'s sign-in-first ordering. */
+/** Run the held `docker login` if the docker CLI is available; "held" otherwise (the caller
+ *  re-invokes after installing dependencies). Exported for `up`'s sign-in-first ordering.
+ *  Returns "done" | "failed" | "held" | "none" so recovery flows can branch on the outcome. */
 export function applyRegistryLogin() {
-  if (!pendingPullCred) return;
-  if (exec("docker", ["--version"]).status !== 0) return; // not installed yet — hold on
+  if (!pendingPullCred) return "none";
+  if (exec("docker", ["--version"]).status !== 0) return "held"; // not installed yet — hold on
   const { username, token } = pendingPullCred;
   const registry = pendingPullCred.registry || "ghcr.io";
   const login = exec("docker", ["login", registry, "-u", username, "--password-stdin"], {
     input: token,
   });
-  if (login.status === 0) log(dim(`  Registry sign-in ok — the runtime image pulls with your account.`));
-  else warn(`Couldn't sign in to ${registry} — a private runtime image won't pull. (${login.stderr || "docker login failed"})`);
   pendingPullCred = null;
+  if (login.status === 0) {
+    log(dim(`  Registry sign-in ok — the runtime image pulls with your account.`));
+    return "done";
+  }
+  warn(`Couldn't sign in to ${registry} — a private runtime image won't pull. (${login.stderr || "docker login failed"})`);
+  return "failed";
+}
+
+/**
+ * Refresh THIS box's image-pull credential without touching its registration — the recovery
+ * for an expired/missing `docker login` (fleet-wide whenever the CP-held PAT rotates). A
+ * quick sign-in (device flow on servers, loopback on desktops, intent "refresh" so the
+ * consent card says what's actually happening) mints the short-lived session, and the
+ * pull credential rides it. Returns true when the docker login landed. Throws on ceremony
+ * failure — callers decide between fail() and a soft fallback.
+ */
+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 } = await consentSession({ host: boxUrl, name, intent: "refresh", domain });
+  return (await registryLogin(token)) === "done";
 }
 
 /**
@@ -298,179 +234,38 @@ 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}` },
-      });
-      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;
   } catch {
     return false;
   }
 }
 
-/** 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}` };
-  }
+/** After a successful unlink the .env trio is DEAD — presence isn't validity, and leaving
+ *  it made the next `up` skip the ceremony entirely and die at an unauthorized pull (hit
+ *  live 2026-08-14). Scrub it so `isLinked` answers honestly and `up` signs in afresh. */
+function scrubCredentials(dir) {
+  unsetEnv(dir, "ALEXANDR_INSTANCE_ID");
+  unsetEnv(dir, "ALEXANDR_RUNTIME_SECRET");
+  unsetEnv(dir, "ALEXANDR_WORKSPACE_ID");
 }
 
 async function isRunning(dir) {

package/src/prompt.js

@@ -114,3 +114,59 @@ export async function ask(question, { def = "", validate, input = process.stdin,
     return value;
   }
 }
+
+/**
+ * A HIDDEN one-line input — for a secret, and only for a secret.
+ *
+ * ⚠⚠ THE VALUE NEVER TOUCHES ARGV. A command line is in the shell's history, in
+ * `ps` output for every user on the box while the process lives, and in any CI
+ * log that echoes the command — so `alexandr app secrets set NAME value` is
+ * refused by the parser, and this is what replaces it. Nothing is echoed and
+ * nothing is re-printed on the confirmation line.
+ *
+ * ⚠ Windows-safe by construction: pure `readline` with the output muted, no
+ * `stty`, no `/bin/sh`. `readline`'s own terminal handling raw-modes the TTY on
+ * both platforms; the muted stream swallows every write it makes while the
+ * question is up, so the keystrokes leave no trace on screen. `terminal: true`
+ * is what makes it use that handling rather than plain line buffering.
+ *
+ * Returns the raw string, untrimmed — a secret may legitimately end in
+ * whitespace, and it is the caller that decides whether an empty one is a
+ * refusal.
+ */
+export function secret(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    let muted = false;
+    // A thin write-only proxy over the real stream: readline draws its prompt
+    // through this, and once the question is on screen every echo is dropped.
+    const masked = Object.create(output);
+    masked.write = (chunk, ...rest) => (muted ? true : output.write(chunk, ...rest));
+
+    const rl = readline.createInterface({ input, output: masked, terminal: true });
+    rl.on("SIGINT", () => abort(output));
+    rl.question(`${cyan("›")} ${bold(question)} `, (answer) => {
+      muted = false;
+      rl.close();
+      // The prompt line is overwritten rather than left with a blank tail —
+      // there is nothing to confirm back, so it says only that it was read.
+      output.write(`\x1b[2K\r${green("✓")} ${question} ${dim("·")} read from the prompt\n`);
+      resolve(answer ?? "");
+    });
+    muted = true;
+  });
+}
+
+/**
+ * A secret from a PIPE — `printf %s "$KEY" | alexandr app secrets set NAME`.
+ *
+ * ⚠ ONE TRAILING NEWLINE IS STRIPPED AND NOTHING ELSE IS. `echo` adds one and
+ * every shell user expects it gone; a second one, or leading whitespace, is
+ * part of the value the person piped and removing it would corrupt a key that
+ * legitimately holds it (a PEM block ends in a newline).
+ */
+export async function readPipedSecret(input = process.stdin) {
+  const chunks = [];
+  for await (const chunk of input) chunks.push(chunk);
+  const raw = Buffer.concat(chunks.map((c) => (typeof c === "string" ? Buffer.from(c) : c))).toString("utf8");
+  return raw.endsWith("\r\n") ? raw.slice(0, -2) : raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+}