alexandr 0.2.2 → 0.3.1

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;
+}

package/src/updater.js

@@ -0,0 +1,276 @@
+// `alexandr updater serve` — the self-host UPDATER SIDECAR (self-host-update-sidecar.md).
+//
+// The kernel runs inside the container an update replaces and must never hold the Docker
+// socket (untrusted app code makes the container the security boundary). So the box carries
+// ONE more process that may: this server, running as the `updater` service of the instance's
+// compose file with the socket mounted, listening on a private unix socket the kernel mounts
+// read-only. Two verbs — `GET /status`, `POST /update` — and nothing else.
+//
+// ⚠ ONE RECIPE, TWO DOORS. This does not implement an update. `POST /update` spawns the SAME
+// `alexandr update` the operator types, as a child process (`update()` calls `fail()`, which
+// exits — a child keeps the server alive), and reads its progress off its own step lines. A
+// change to the recipe is therefore a change to both doors, by construction.
+//
+// ⚠ THE SIDECAR NAMES THE TARGET, NEVER THE CALLER. The kernel may ask for `to`, but the
+// version that runs is the release FEED's current one (or the recorded previous image, for a
+// rollback); a request naming anything else is refused. A compromised kernel cannot make the
+// host pull an image of its choosing.
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readEnv } from "./instance.js";
+import { log, warn, fail, dim } from "./util.js";
+import { EXIT } from "./exit.js";
+
+export const STATE_FILE = ".update-state.json";
+const DEFAULT_SOCKET = "/run/alexandr/updater.sock";
+const DEFAULT_FEED = "https://api.alexandr.so/releases/stable";
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.resolve(fileURLToPath(import.meta.url), "..", "..", "package.json"), "utf8"),
+);
+
+/** The feed a linked box reads — the same derivation the kernel's update check uses. */
+export function feedUrlFor(env) {
+  const explicit = (env.ALEXANDR_RELEASES_URL || "").trim();
+  if (explicit) return explicit;
+  const cp = (env.ALEXANDR_CP_URL || "").trim().replace(/\/+$/, "");
+  return cp ? `${cp}/releases/stable` : DEFAULT_FEED;
+}
+
+/** The phase a `alexandr update` step line announces — the sidecar's progress is the CLI's own words. */
+export function phaseOf(line) {
+  if (/Snapshotting/i.test(line)) return "snapshotting";
+  if (/Pulling the runtime image|Offline update/i.test(line)) return "pulling";
+  if (/Applying the update/i.test(line)) return "restarting";
+  if (/Updated:/i.test(line)) return "done";
+  return null;
+}
+
+/**
+ * The request handler, separated from the socket so a test can drive it with a fake runner
+ * and a fake feed. `deps.runUpdate({ to, rollback, onPhase })` resolves `{ ok, error?, from?, to? }`.
+ */
+export function createUpdaterHandler(deps) {
+  const {
+    instanceDir,
+    feedUrl,
+    runUpdate,
+    fetchImpl = fetch,
+    updaterVersion = pkg.version,
+    now = () => new Date().toISOString(),
+  } = deps;
+  const statePath = path.join(instanceDir, STATE_FILE);
+  let state = readState(statePath) ?? { state: "idle" };
+  let running = null;
+
+  function write(next) {
+    state = { ...next, updaterVersion };
+    try {
+      fs.mkdirSync(instanceDir, { recursive: true });
+      fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    } catch {
+      // The state file is a courtesy to a kernel that restarts mid-update; losing it is not fatal.
+    }
+    return state;
+  }
+
+  async function feedCurrent() {
+    const res = await fetchImpl(feedUrl, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) throw new Error(`the release feed answered ${res.status}`);
+    const body = await res.json();
+    const v = body?.current?.version;
+    if (typeof v !== "string" || !v) throw new Error("the release feed names no current version");
+    return v;
+  }
+
+  async function status() {
+    return { status: 200, body: { ...state, updaterVersion } };
+  }
+
+  async function update(body) {
+    if (running) return { status: 409, body: { error: "an update is already running", ...state } };
+    const rollback = body?.rollback === true;
+    let to = null;
+    if (!rollback) {
+      let current;
+      try {
+        current = await feedCurrent();
+      } catch (e) {
+        return { status: 502, body: { error: `could not read the release feed: ${e.message}` } };
+      }
+      const asked = typeof body?.to === "string" && body.to.trim() ? body.to.trim().replace(/^v/, "") : null;
+      if (asked && asked !== current) {
+        return {
+          status: 409,
+          body: { error: `refused: ${asked} is not the feed's current version (${current})`, current },
+        };
+      }
+      to = current;
+    }
+    const startedAt = now();
+    write({ state: "updating", phase: "starting", to, rollback, startedAt });
+    running = (async () => {
+      let result;
+      try {
+        result = await runUpdate({
+          to,
+          rollback,
+          onPhase: (phase) => write({ ...state, state: "updating", phase }),
+        });
+      } catch (e) {
+        result = { ok: false, error: e?.message || String(e) };
+      }
+      if (result.ok) {
+        write({ state: "done", phase: "done", to: result.to ?? to, from: result.from ?? null, rollback, startedAt, finishedAt: now() });
+      } else {
+        write({ state: "failed", phase: state.phase ?? "starting", to, rollback, startedAt, finishedAt: now(), error: result.error || "update failed" });
+      }
+      running = null;
+    })();
+    return { status: 202, body: { started: true, to, rollback, startedAt } };
+  }
+
+  return {
+    async handle(method, urlPath, body) {
+      if (method === "GET" && urlPath === "/status") return status();
+      if (method === "POST" && urlPath === "/update") return update(body ?? {});
+      return { status: 404, body: { error: "not found" } };
+    },
+    /** Test seam: wait for an in-flight update to settle. */
+    settled: () => running ?? Promise.resolve(),
+  };
+}
+
+function readState(p) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+    // A box that restarted mid-update: the child is gone with the old process, so "updating" is stale.
+    return parsed?.state === "updating" ? { ...parsed, state: "failed", error: "the updater restarted mid-update" } : parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * THE recipe, as a child: `alexandr update --dir <instance> --project <name> [--to v|--rollback] --yes`.
+ * `ALEXANDR_UPDATER_INSIDE=1` tells `update` it is running from the sidecar, so its compose
+ * calls leave the `updater` service alone (a container cannot recreate itself mid-run).
+ */
+export function spawnUpdate({ instanceDir, projectName, bin }) {
+  return ({ to, rollback, onPhase }) =>
+    new Promise((resolve) => {
+      const args = [bin, "update", "--dir", instanceDir, "--project", projectName, "--yes"];
+      if (rollback) args.push("--rollback");
+      else if (to) args.push("--to", `v${to}`);
+      const child = spawn(process.execPath, args, {
+        env: { ...process.env, ALEXANDR_UPDATER_INSIDE: "1", FORCE_COLOR: "0", NO_COLOR: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let out = "";
+      let from = null;
+      let after = null;
+      const onData = (chunk) => {
+        const text = String(chunk);
+        out += text;
+        process.stdout.write(text);
+        for (const line of text.split("\n")) {
+          const phase = phaseOf(line);
+          if (phase) onPhase(phase);
+          const m = /Updated:\s*(\S+)\s*→\s*(\S+)/.exec(line);
+          if (m) [, from, after] = m;
+        }
+      };
+      child.stdout.on("data", onData);
+      child.stderr.on("data", onData);
+      child.on("close", (code) => {
+        if (code === 0) resolve({ ok: true, from, to: after ?? to });
+        else resolve({ ok: false, error: lastLine(out) || `alexandr update exited ${code}` });
+      });
+      child.on("error", (e) => resolve({ ok: false, error: e.message }));
+    });
+}
+
+// The child's last line, without colour codes or the CLI's own status glyph (`✗ `, `▸ `): the
+// words are the operator's, the decoration was the terminal's.
+const lastLine = (s) =>
+  s
+    .split("\n")
+    .map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").replace(/^[✗✓▸!]\s*/u, "").trim())
+    .filter(Boolean)
+    .pop() ?? "";
+
+// ---------------------------------------------------------------- the verb
+export async function updater(flags) {
+  const sub = flags._.shift();
+  if (sub !== "serve") fail("usage: alexandr updater serve  (runs inside the `updater` sidecar)", EXIT.USAGE);
+  const instanceDir = String(flags.dir || process.env.ALEXANDR_INSTANCE_DIR || "").trim();
+  const projectName = String(flags.project || process.env.ALEXANDR_COMPOSE_PROJECT || "").trim();
+  if (!instanceDir || !projectName) {
+    fail("updater serve needs the instance directory and compose project (ALEXANDR_INSTANCE_DIR / ALEXANDR_COMPOSE_PROJECT).", EXIT.USAGE);
+  }
+  const socketPath = String(flags.socket || process.env.ALEXANDR_UPDATER_SOCKET || DEFAULT_SOCKET);
+  const env = readEnv(instanceDir);
+  const feedUrl = feedUrlFor({ ...env, ...process.env });
+  const bin = path.resolve(fileURLToPath(import.meta.url), "..", "..", "bin.js");
+  const handler = createUpdaterHandler({
+    instanceDir,
+    feedUrl,
+    runUpdate: spawnUpdate({ instanceDir, projectName, bin }),
+  });
+
+  fs.mkdirSync(path.dirname(socketPath), { recursive: true });
+  try {
+    fs.unlinkSync(socketPath);
+  } catch {
+    /* no stale socket */
+  }
+  const server = http.createServer(async (req, res) => {
+    let body = "";
+    req.on("data", (c) => {
+      body += c;
+      if (body.length > 4096) req.destroy();
+    });
+    req.on("end", async () => {
+      let parsed = {};
+      if (body) {
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "bad json" }));
+          return;
+        }
+      }
+      const out = await handler.handle(req.method, (req.url || "/").split("?")[0], parsed);
+      res.writeHead(out.status, { "content-type": "application/json" });
+      res.end(JSON.stringify(out.body));
+    });
+  });
+  server.listen(socketPath, () => {
+    // Group-readable + writable so the kernel (a different uid) can connect; the volume is the ACL.
+    try {
+      fs.chmodSync(socketPath, 0o666);
+    } catch {
+      /* best effort */
+    }
+    log(`alexandr updater v${pkg.version} — listening on ${socketPath}`);
+    log(dim(`  instance ${instanceDir} · project ${projectName} · feed ${feedUrl}`));
+  });
+  const stop = () => {
+    server.close();
+    try {
+      fs.unlinkSync(socketPath);
+    } catch {
+      /* gone */
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  await new Promise(() => {});
+  warn("unreachable");
+}

package/templates/docker-compose.yml

@@ -16,15 +16,47 @@ services:
       # The HOST side of the port map below — inside the container the kernel only
       # knows its internal port, and must not advertise that as its reachable URL.
       ALEXANDR_ADVERTISED_PORT: ${ALEXANDR_KERNEL_PORT:-3030}
+      # Where the updater sidecar listens (a read-only mount below). The kernel reports
+      # `updater.available` from whether something answers here — never assumes.
+      ALEXANDR_UPDATER_SOCKET: /run/alexandr/updater.sock
     env_file:
       - path: ./.env
         required: false            # every var is optional; the CLI writes this file
     volumes:
       - data:/data                 # instance state: OS db, installed apps, blobs
+      # The updater sidecar's socket (below) — read-only: the kernel may ASK for an
+      # update over it and holds no Docker of its own.
+      - updater_run:/run/alexandr:ro
     ports:
       - "127.0.0.1:${ALEXANDR_KERNEL_PORT:-3030}:3030"   # loopback only
     restart: unless-stopped
 
+  # THE UPDATER SIDECAR (self-host-update-sidecar.md): the `alexandr` CLI in a container, the
+  # ONE process on this host allowed to hold the Docker socket, so the desktop app's update
+  # sheet can say "Update now" instead of handing over a command to copy. It runs the same
+  # `alexandr update` the operator would type — snapshot /data, pin, pull, restart, verify —
+  # when the kernel asks over the private socket in `updater_run`, and it resolves the target
+  # from the release feed itself (the kernel never names an image).
+  #
+  # Under the `updater` profile: the CLI passes `--profile updater` unless the operator set
+  # `alexandr up --no-updater` (ALEXANDR_UPDATER=off). Inside the container the instance
+  # directory is mounted at its HOST path, so compose's relative files resolve identically.
+  updater:
+    image: ghcr.io/alexandrco/alexandr-updater:${ALEXANDR_UPDATER_IMAGE_TAG:-latest}
+    profiles: ["updater"]
+    environment:
+      ALEXANDR_INSTANCE_DIR: ${ALEXANDR_INSTANCE_DIR:-/nonexistent}
+      ALEXANDR_COMPOSE_PROJECT: ${ALEXANDR_COMPOSE_PROJECT:-alexandr}
+      ALEXANDR_UPDATER_SOCKET: /run/alexandr/updater.sock
+    env_file:
+      - path: ./.env
+        required: false            # ALEXANDR_CP_URL / ALEXANDR_RELEASES_URL → the feed it reads
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock                 # THE socket. Only here.
+      - ${ALEXANDR_INSTANCE_DIR:-/nonexistent}:${ALEXANDR_INSTANCE_DIR:-/nonexistent}
+      - updater_run:/run/alexandr
+    restart: unless-stopped
+
   # Public front door. Only started under the "public" profile — i.e. when a
   # domain is configured (`alexandr up --domain …`). Pure-local runs skip it, so
   # no root is needed for :80/:443 and there's no TLS machinery to babysit.
@@ -49,3 +81,4 @@ volumes:
   data:
   caddy_data:
   caddy_config:
+  updater_run:                     # the updater's unix socket; the kernel mounts it read-only

package/templates/env.example

@@ -9,6 +9,16 @@
 
 # ---- image (the CLI pins this for `update --to <tag>` / `--rollback`) -------
 # ALEXANDR_IMAGE=ghcr.io/alexandrco/alexandr-kernel:latest
+# ---- the updater sidecar (self-host-update-sidecar.md) ----------------------
+# The `updater` service lets the desktop app's update sheet say "Update now": the
+# alexandr CLI in a container, the one process on this host holding the Docker
+# socket, running the same `alexandr update` you would type. On by default; opt out
+# with `alexandr up --no-updater` (writes the line below). The three vars after it
+# are WRITTEN BY THE CLI on every `up`/`update` — never fill them by hand.
+# ALEXANDR_UPDATER=off
+# ALEXANDR_INSTANCE_DIR=        # this directory, at its host path (mounted at the same path)
+# ALEXANDR_COMPOSE_PROJECT=     # the compose project the sidecar drives (the host's, verbatim)
+# ALEXANDR_UPDATER_IMAGE_TAG=   # the CLI version that installed it (= the sidecar's version)
 
 # ---- account link (REQUIRED — the runtime refuses to serve unlinked) --------
 # Every runtime must be linked to an alexandr account before it serves anyone