alexandr 0.1.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alexandr",
-  "version": "0.1.2",
+  "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": {

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
@@ -105,6 +107,23 @@ export async function runLinkCeremony(inst, flags) {
     (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());
@@ -123,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;
@@ -143,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"}).`);
@@ -173,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);
 }
 
 /**
@@ -226,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));
@@ -241,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 {