alexandr 0.1.1 → 0.2.0

package/README.md

@@ -25,9 +25,11 @@ never prompt (`up` stays an idempotent restart).
 Sign-in comes right after the questions: every runtime is linked to an alexandr
 account before it serves anyone, and the entitlement gate fires **before anything
 touches the system** — an account that may not register walks away from a box
-holding three text files, not a Docker install. On a desktop the CLI asks before
-opening your browser; on a headless server it prints the tunnel + link steps to
-run from your computer.
+holding three text files, not a Docker install. On a **headless server** the CLI
+uses the device flow: it shows a short code + link, you confirm from any browser
+on any device (no tunnels, no port forwarding), and the terminal continues by
+itself. On a desktop it asks before opening your browser for the instant
+loopback hand-off.
 
 Only after sign-in does `up` handle dependencies: on a fresh **Linux** server,
 when Docker or Compose v2 is missing it offers to install them right there

package/bin.js

@@ -1,7 +1,20 @@
 #!/usr/bin/env node
 // Public entrypoint for the `alexandr` CLI. Keep this a thin shim; logic lives
-// in ./src. Plain Node (no Bun, no deps) so it runs anywhere Node 20+ is.
-import { run } from "./src/cli.js";
+// in ./src. Plain Node (no Bun, no deps) so it runs anywhere Node 18+ is.
+
+// Our own version guard, so nobody meets npm's EBADENGINE wall: package.json
+// declares >=18 (what Ubuntu LTS's apt ships, and provably sufficient — the CLI
+// is dependency-free), and anything older gets ONE styled line instead of a trace.
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 18) {
+  process.stderr.write(
+    `\x1b[31m✗\x1b[0m alexandr needs Node 18 or newer — this is Node ${process.versions.node}.\n` +
+    `  On Ubuntu/Debian: apt install -y npm    (or use nodesource for a current LTS)\n`,
+  );
+  process.exit(1);
+}
+
+const { run } = await import("./src/cli.js");
 
 run().catch((err) => {
   process.stderr.write(`${err?.stack || err}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Run the alexandr workspace runtime locally — a thin Docker front door (npx alexandr up). Pulls + boots the published kernel image.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=18"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/commands.js

@@ -173,6 +173,12 @@ export async function up(flags) {
 
   if (flags.port) setEnv(inst.dir, "ALEXANDR_KERNEL_PORT", String(flags.port));
   if (flags.domain) setEnv(inst.dir, "ALEXANDR_DOMAIN", String(flags.domain));
+  // Persist the display name so a RETRIED ceremony reuses the wizard's answer — the
+  // first attempt on the aos box lost "AOS" to the default because it lived only in
+  // that run's memory (the ceremony it fed timed out).
+  if (typeof flags.name === "string" && flags.name.trim()) {
+    setEnv(inst.dir, "ALEXANDR_WORKSPACE_NAME", flags.name.trim());
+  }
 
   // Sign-in comes FIRST (account-required-runtimes D3) — now literally: the entitlement
   // gate fires before anything system-mutating, so a refused account walks away from a

package/src/link.js

@@ -14,7 +14,7 @@ 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 } from "./util.js";
+import { log, dim, bold, cyan, fail, step, ok, warn, openURL, sleep } from "./util.js";
 import { resolveInstance, isMaterialized, readEnv, kernelPort, setEnv } from "./instance.js";
 import { kernelUrl, health, waitPosture } from "./probe.js";
 import { compose, exec } from "./docker.js";
@@ -90,8 +90,10 @@ export async function link(flags) {
   ok(`Linked. This runtime signs in with your alexandr account — open it in the Alexandr app (your account: ${APP_URL}/account).`);
 }
 
-/** The browser OAuth+PKCE ceremony + registration. Writes the .env credential trio on success;
- *  fails the process on any break in the chain. Exported for `up`'s revoked-recovery lane. */
+/** The account-link ceremony + registration. Writes the .env credential trio on success;
+ *  fails the process on any break in the chain. Exported for `up`'s revoked-recovery lane.
+ *  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
@@ -101,8 +103,27 @@ export async function runLinkCeremony(inst, flags) {
     ? `https://${String(domain).replace(/^https?:\/\//, "").replace(/\/+$/, "")}`
     : kernelUrl(kernelPort(inst.dir));
   const name =
-    typeof flags.name === "string" && flags.name.trim() ? flags.name.trim() : "My self-hosted workspace";
+    (typeof flags.name === "string" && flags.name.trim()) ||
+    (readEnv(inst.dir).ALEXANDR_WORKSPACE_NAME || "").trim() ||
+    "My self-hosted workspace";
 
+  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());
@@ -121,7 +142,6 @@ export async function runLinkCeremony(inst, flags) {
       name,
     }).toString();
 
-  step(`Link ${boxUrl} to your alexandr account`);
   await presentAuthUrl(authUrl, { port, domain });
 
   let cb;
@@ -141,10 +161,56 @@ export async function runLinkCeremony(inst, flags) {
   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(
     `${CP_URL}/instances`,
     { name, url: boxUrl },
-    { authorization: `Bearer ${tok.data.token}` },
+    { authorization: `Bearer ${sessionToken}` },
   );
   if (!reg.data?.instanceId || !reg.data?.telemetryToken) {
     fail(`Link failed: could not register this runtime (${reg.error ?? "malformed response"}).`);
@@ -171,7 +237,7 @@ export async function runLinkCeremony(inst, flags) {
   setEnv(inst.dir, "ALEXANDR_RUNTIME_SECRET", reg.data.telemetryToken);
   if (reg.data.workspaceId) setEnv(inst.dir, "ALEXANDR_WORKSPACE_ID", reg.data.workspaceId);
   ok("Signed in — this runtime is linked to your account.");
-  await registryLogin(tok.data.token);
+  await registryLogin(sessionToken);
 }
 
 /**
@@ -224,6 +290,25 @@ export async function unlinkFromAccount(inst, flags) {
     log(dim("  (no workspace id recorded — remove it from your account page instead)"));
     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));
@@ -239,7 +324,6 @@ export async function unlinkFromAccount(inst, flags) {
       host: kernelUrl(kernelPort(inst.dir)),
       name: "Unlink this runtime",
     }).toString();
-  step("Sign in to remove this runtime from your account…");
   await presentAuthUrl(authUrl, { port, domain: (env.ALEXANDR_DOMAIN || "").trim() || undefined });
   let cb;
   try {
@@ -309,7 +393,7 @@ export async function presentAuthUrl(authUrl, { port, domain, headless = isHeadl
 }
 
 /** Start a loopback listener for the OAuth redirect. Resolves {code,state} when /callback is hit. */
-function startLoopback() {
+export function startLoopback() {
   let resolveFn, rejectFn;
   const done = new Promise((res, rej) => {
     resolveFn = res;
@@ -317,6 +401,20 @@ function startLoopback() {
   });
   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();

package/templates/env.example

@@ -21,6 +21,8 @@
 # ALEXANDR_INSTANCE_ID=
 # ALEXANDR_RUNTIME_SECRET=
 # ALEXANDR_WORKSPACE_ID=        # account-side record id (used by `destroy --unlink`)
+# ALEXANDR_WORKSPACE_NAME=      # display name for registration (the wizard writes it,
+#                               # so a retried sign-in reuses your answer)
 
 # Public domain for Caddy auto-HTTPS. Setting this starts the "public" profile — the
 # supported way to reach the runtime from another machine. Without a domain the