slidemind 0.3.20 → 0.4.1

package/src/workspace/auth.mjs

@@ -0,0 +1,256 @@
+// Who may talk to the workspace API.
+//
+// Two callers, two credentials:
+//   CLI      `Authorization: Bearer <cliBearer>` from the user-private descriptor.
+//   Browser  the workspace's link key, which the CLI (bearer) puts in the URL
+//            fragment of every link it hands out (`#bootstrap=<key>`); the page
+//            exchanges it at POST /api/v1/session for an HttpOnly SameSite=Strict
+//            cookie and a CSRF token it must echo on every mutation.
+//
+// The link key is an HMAC under session.key: the same in every link and after
+// every restart, so a link brings the user to its deck every time it is clicked,
+// in any browser (an agent app's own pane included), with nothing to expire —
+// the user's call, 2026-10-08: the workspace is one always-available thing, and
+// once-only, minute-long tokens only added friction. They bought nothing: a
+// 127.0.0.1 link is useless off this machine, and a program on it that can read
+// the link can read session.key too. What keeps everyone else out is unchanged —
+// another site or tab gets neither the key nor the cookie (SameSite=Strict, the
+// Host check and `frame-ancestors 'self'` in server.mjs), and a local tool
+// without the user's files holds neither the key nor the CLI bearer. Deleting
+// session.key rotates the key and signs every browser out.
+//
+// With `storeDir` (the daemon passes its config dir) a browser session survives
+// a daemon restart — the daemon restarts on a crash, a reboot and every CLI
+// update, and a user must not be signed out by any of them. On disk:
+//   session.key    32 random bytes (0600); the link key, csrf and gate tokens are HMACs under it
+//   sessions.json  sha256(cookie) → { expiresAt, lastSeen } (0600)
+// A cookie is stored only as its hash, and the tokens derived from the key are
+// recomputed, never stored. Sessions slide (400 days from the last use, the
+// longest a browser keeps a cookie) and are capped at the 50 most recently used.
+// Without `storeDir` everything lives in this process (tests).
+
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { authorizeBearer } from "./server.mjs";
+
+export const COOKIE = "slidemind_ws";
+// As long as a browser keeps a cookie at all (Chrome caps Max-Age at 400 days),
+// sliding: a workspace the user opens at all never signs them out.
+export const SESSION_TTL_MS = 400 * 24 * 60 * 60 * 1000;
+export const SESSION_CAP = 50;
+// lastSeen is written back at most this often per session: every request would
+// otherwise rewrite the file
+const TOUCH_MS = 60 * 60 * 1000;
+
+const safeEqual = (a, b) => {
+  const x = Buffer.from(String(a ?? ""));
+  const y = Buffer.from(String(b ?? ""));
+  return x.length === y.length && x.length > 0 && timingSafeEqual(x, y);
+};
+const sha = (s) => createHash("sha256").update(String(s)).digest("hex");
+
+function cookieValue(req, name) {
+  const header = String(req.headers.cookie ?? "");
+  for (const part of header.split(";")) {
+    const [k, ...v] = part.trim().split("=");
+    if (k === name) return v.join("=");
+  }
+  return null;
+}
+
+/** The persisted HMAC key: read it, or create it once (a racing daemon's file wins). */
+function loadKey(storeDir) {
+  const file = path.join(storeDir, "session.key");
+  const read = () => {
+    const k = fs.readFileSync(file);
+    return k.length === 32 ? k : null;
+  };
+  try {
+    const k = read();
+    if (k) return k;
+  } catch {
+    // none yet
+  }
+  fs.mkdirSync(storeDir, { recursive: true, mode: 0o700 });
+  const key = randomBytes(32);
+  try {
+    fs.writeFileSync(file, key, { mode: 0o600, flag: "wx" });
+    return key;
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+  const k = read();
+  if (k) return k;
+  // a truncated key file: replace it — every session it signed is unreadable anyway
+  fs.writeFileSync(file, key, { mode: 0o600 });
+  return key;
+}
+
+/**
+ * `createAuth({ bearer, storeDir = null })`
+ *   linkToken()             → { token }   the link key (CLI, bearer-authenticated route)
+ *   exchange(token)         → { cookie, csrfToken } | null   (the link key, as often as it is clicked)
+ *   authenticate(req)       → { kind: "cli" } | { kind: "browser", csrfToken } | null
+ *   allowMutation(req, who, origin) → null | error code
+ *   cookieHeader(cookie)    → the Set-Cookie value (Max-Age = the session TTL)
+ *   renewalHeader(req)      → a Set-Cookie renewing the cookie when its session just slid, else null
+ *   gateTokenFor(deckId)    → the embedded gates' per-deck token (stable across restarts)
+ *   gateTokenValid(token, deckId) → bool
+ */
+export function createAuth({ bearer, storeDir = null }) {
+  const key = storeDir ? loadKey(storeDir) : randomBytes(32);
+  const storeFile = storeDir ? path.join(storeDir, "sessions.json") : null;
+  // Two daemons on 127.0.0.1 share cookies by host, whatever their ports: the
+  // name carries the config dir so one workspace never overwrites another's.
+  const cookieName = storeDir ? `${COOKIE}_${sha(path.resolve(storeDir)).slice(0, 8)}` : COOKIE;
+  const mac = (s) => createHmac("sha256", key).update(s).digest("base64url");
+  const linkKey = mac("link");
+  const sessions = new Map(); // sha256(cookie) → { expiresAt, lastSeen }
+  let storeStamp = ""; // mtime:size of the file as last read or written
+
+  const load = () => {
+    if (!storeFile) return;
+    let st;
+    try {
+      st = fs.statSync(storeFile);
+    } catch {
+      return;
+    }
+    if (`${st.mtimeMs}:${st.size}` === storeStamp) return;
+    storeStamp = `${st.mtimeMs}:${st.size}`;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(storeFile, "utf8"));
+    } catch {
+      return; // unreadable: start over rather than fail every request
+    }
+    const now = Date.now();
+    for (const [h, s] of Object.entries(data?.sessions ?? {})) {
+      if (!s || !(s.expiresAt > now)) continue;
+      const mine = sessions.get(h);
+      if (!mine || mine.expiresAt < s.expiresAt) sessions.set(h, { expiresAt: s.expiresAt, lastSeen: s.lastSeen ?? 0 });
+    }
+  };
+  const sweep = () => {
+    const now = Date.now();
+    for (const [h, s] of sessions) if (s.expiresAt <= now) sessions.delete(h);
+    if (sessions.size > SESSION_CAP) {
+      const oldest = [...sessions].sort(([, a], [, b]) => a.lastSeen - b.lastSeen);
+      for (const [h] of oldest.slice(0, sessions.size - SESSION_CAP)) sessions.delete(h);
+    }
+  };
+  // Persisting is best effort: a session that cannot be written still works
+  // until this process ends, which is exactly the in-memory behaviour.
+  const save = () => {
+    if (!storeFile) return;
+    sweep();
+    const tmp = `${storeFile}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+      fs.writeFileSync(tmp, JSON.stringify({ version: 1, sessions: Object.fromEntries(sessions) }), { mode: 0o600 });
+      fs.renameSync(tmp, storeFile);
+      const st = fs.statSync(storeFile);
+      storeStamp = `${st.mtimeMs}:${st.size}`;
+    } catch {
+      fs.rmSync(tmp, { force: true });
+    }
+  };
+  // another daemon on this store (the one being replaced) may hold a newer state:
+  // merge it in before deciding, and before writing ours over it
+  const sync = () => {
+    load();
+    sweep();
+  };
+  load();
+  sweep();
+
+  const cookieHeader = (cookie) => `${cookieName}=${cookie}; Path=/; Max-Age=${Math.floor(SESSION_TTL_MS / 1000)}; HttpOnly; SameSite=Strict`;
+  // Requests whose session just slid: their response re-sends the cookie with a
+  // fresh Max-Age (renewalHeader), or the browser would drop it 30 days after
+  // the FIRST sign-in however often it was used.
+  const renewed = new WeakMap(); // req → cookie
+  /** The session behind this request's cookie, slid forward; null when there is none. */
+  const sessionOf = (req) => {
+    const c = cookieValue(req, cookieName);
+    if (!c) return null;
+    const h = sha(c);
+    let s = sessions.get(h);
+    if (!s || s.expiresAt <= Date.now()) {
+      sync(); // a session minted by the process that ran before us
+      s = sessions.get(h);
+    }
+    if (!s || s.expiresAt <= Date.now()) return null;
+    const now = Date.now();
+    if (now - s.lastSeen > TOUCH_MS) {
+      s.lastSeen = now;
+      s.expiresAt = now + SESSION_TTL_MS;
+      load();
+      sessions.set(h, s);
+      save();
+      renewed.set(req, c);
+    }
+    return c;
+  };
+
+  return {
+    linkToken() {
+      return { token: linkKey };
+    },
+    exchange(token) {
+      if (!safeEqual(token, linkKey)) return null;
+      sync();
+      const cookie = randomBytes(32).toString("base64url");
+      const now = Date.now();
+      sessions.set(sha(cookie), { expiresAt: now + SESSION_TTL_MS, lastSeen: now });
+      save();
+      return { cookie, csrfToken: mac(`csrf:${cookie}`) };
+    },
+    cookieHeader,
+    /**
+     * The Set-Cookie that renews this request's cookie (same value, a full
+     * Max-Age again) when its session just slid — at most once an hour per
+     * session; null otherwise. Call it for an authenticated browser request.
+     */
+    renewalHeader(req) {
+      if (!renewed.has(req)) sessionOf(req);
+      const c = renewed.get(req);
+      return c ? cookieHeader(c) : null;
+    },
+    authenticate(req) {
+      if (authorizeBearer(req, bearer)) return { kind: "cli" };
+      const c = sessionOf(req);
+      return c ? { kind: "browser", csrfToken: mac(`csrf:${c}`) } : null;
+    },
+    /**
+     * A cookie-authenticated mutation must come from OUR page: the CSRF token
+     * echoed in `X-CSRF-Token`, and the browser's own origin evidence
+     * (`Origin`, else `Sec-Fetch-Site`) naming this authority. A request
+     * carrying neither is not a page of ours talking.
+     */
+    allowMutation(req, who, origin) {
+      if (!who) return "unauthorized";
+      if (who.kind === "cli") return null;
+      if (!safeEqual(req.headers["x-csrf-token"], who.csrfToken)) return "csrf_required";
+      const o = req.headers.origin;
+      if (o !== undefined) return o === origin ? null : "cross_origin";
+      const site = req.headers["sec-fetch-site"];
+      if (site === "same-origin") return null;
+      return "cross_origin";
+    },
+    /** The token an embedded gate page carries in its decision URL; the same after a restart. */
+    gateTokenFor(deckId) {
+      return mac(`gate:${deckId}`);
+    },
+    gateTokenValid(token, deckId) {
+      return typeof deckId === "string" && deckId.length > 0 && safeEqual(token, mac(`gate:${deckId}`));
+    },
+    /** The cookie this workspace sets (scoped per config dir). */
+    cookieName,
+    /** Test/inspection seam: how many live browser sessions. */
+    get sessionCount() {
+      sweep();
+      return sessions.size;
+    },
+  };
+}

package/src/workspace/autostart.mjs

@@ -0,0 +1,204 @@
+// The workspace's login item (doc 21 → *Launch and stop*): the one place a user
+// answers must be running before any agent asks, because an agent in Codex's
+// sandbox can neither start it nor keep a detached process (and, with network
+// off, cannot even connect to it). `slidemind setup` registers this; it runs
+// `slidemind workspace start` — a silent "start it unless it runs", never a
+// supervisor: the daemon replaces itself by starting its successor and
+// exiting, and a supervisor that restarts on exit would fight that.
+//
+//   macOS    LaunchAgent, at login and every 60 s (AbandonProcessGroup, so the
+//            detached daemon outlives the one-shot job)
+//   Windows  a hidden launcher in the Startup folder, at login
+//   Linux    an XDG autostart entry, at login
+//
+// Every function takes `{ home, platform, run }` so a test never touches the
+// real login items of the machine it runs on.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const LABEL = "com.statworx.slidemind.workspace";
+const MAC_INTERVAL_S = 60;
+
+const defaults = (o = {}) => ({
+  home: o.home ?? os.homedir(),
+  platform: o.platform ?? process.platform,
+  run: o.run ?? ((cmd, args) => execFileSync(cmd, args, { stdio: "ignore" })),
+  uid: o.uid ?? (typeof process.getuid === "function" ? process.getuid() : null),
+  env: o.env ?? process.env,
+});
+
+/** Where this platform keeps the login item; null where there is none. */
+export function autostartPath(opts = {}) {
+  const { home, platform, env } = defaults(opts);
+  if (platform === "darwin") return path.join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+  if (platform === "win32") return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "slidemind-workspace.vbs");
+  if (platform === "linux") return path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "autostart", "slidemind-workspace.desktop");
+  return null;
+}
+
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/**
+ * The login item's file for `node <script> workspace start`. `env` carries what
+ * a login job lacks: a PATH, and the config dir when the user moved it (the
+ * daemon must find THEIR registry and session key).
+ */
+export function autostartFile({ platform, nodePath, scriptPath, env = {}, home }) {
+  const args = [nodePath, scriptPath, "workspace", "start"];
+  if (platform === "darwin") {
+    const vars = Object.entries(env)
+      .filter(([, v]) => typeof v === "string" && v)
+      .map(([k, v]) => `      <key>${xml(k)}</key><string>${xml(v)}</string>\n`)
+      .join("");
+    return (
+      '<?xml version="1.0" encoding="UTF-8"?>\n' +
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
+      '<plist version="1.0">\n<dict>\n' +
+      `  <key>Label</key><string>${LABEL}</string>\n` +
+      "  <key>ProgramArguments</key>\n  <array>\n" +
+      args.map((a) => `    <string>${xml(a)}</string>\n`).join("") +
+      "  </array>\n" +
+      "  <key>RunAtLoad</key><true/>\n" +
+      `  <key>StartInterval</key><integer>${MAC_INTERVAL_S}</integer>\n` +
+      "  <key>AbandonProcessGroup</key><true/>\n" +
+      "  <key>ProcessType</key><string>Background</string>\n" +
+      `  <key>WorkingDirectory</key><string>${xml(home)}</string>\n` +
+      "  <key>StandardOutPath</key><string>/dev/null</string>\n" +
+      "  <key>StandardErrorPath</key><string>/dev/null</string>\n" +
+      (vars ? `  <key>EnvironmentVariables</key>\n  <dict>\n${vars}  </dict>\n` : "") +
+      "</dict>\n</plist>\n"
+    );
+  }
+  if (platform === "win32") {
+    // WScript.Shell.Run(cmd, 0 = hidden window, False = do not wait)
+    const cmd = args.map((a) => `""${a}""`).join(" ");
+    const sets = Object.entries(env)
+      .filter(([k, v]) => k !== "PATH" && typeof v === "string" && v)
+      .map(([k, v]) => `sh.Environment("Process")("${k}") = "${String(v).replace(/"/g, '""')}"\r\n`)
+      .join("");
+    return `Set sh = CreateObject("WScript.Shell")\r\n${sets}sh.Run "${cmd}", 0, False\r\n`;
+  }
+  if (platform === "linux") {
+    const quote = (a) => `"${String(a).replace(/(["`$\\])/g, "\\$1")}"`;
+    const envPrefix = Object.entries(env)
+      .filter(([k, v]) => k !== "PATH" && typeof v === "string" && v)
+      .map(([k, v]) => `${k}=${quote(v)}`);
+    const exec = envPrefix.length ? ["env", ...envPrefix, ...args.map(quote)].join(" ") : args.map(quote).join(" ");
+    return `[Desktop Entry]\nType=Application\nName=slidemind workspace\nComment=Keeps the slidemind workspace running\nExec=${exec}\nNoDisplay=true\nX-GNOME-Autostart-enabled=true\n`;
+  }
+  return null;
+}
+
+/**
+ * Register (or refresh) the login item and load it now. Resolves
+ * `{ installed, path, reason? }` — never throws: a machine where it cannot be
+ * registered still has a workspace started by setup and by every unsandboxed
+ * CLI run; the login item only makes it survive a reboot without one.
+ */
+export function installAutostart({ nodePath, scriptPath, env = {} }, opts = {}) {
+  const o = defaults(opts);
+  const file = autostartPath(o);
+  if (!file) return { installed: false, path: null, reason: `no login items on ${o.platform}` };
+  const body = autostartFile({ platform: o.platform, nodePath, scriptPath, env, home: o.home });
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, body, { mode: 0o644 });
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    return { installed: false, path: file, reason: err?.code ?? err?.message ?? String(err) };
+  }
+  if (o.platform === "darwin" && o.uid !== null) {
+    // reload: bootout of a job that is not loaded fails, and that is fine
+    const domain = `gui/${o.uid}`;
+    try {
+      o.run("launchctl", ["bootout", `${domain}/${LABEL}`]);
+    } catch {
+      // not loaded yet
+    }
+    try {
+      o.run("launchctl", ["bootstrap", domain, file]);
+    } catch (err) {
+      return { installed: true, path: file, loaded: false, reason: `written; loads at the next login (${err?.message ?? err})` };
+    }
+    return { installed: true, path: file, loaded: true };
+  }
+  return { installed: true, path: file, loaded: false };
+}
+
+/** Remove the login item (and unload it on macOS). `{ removed, path }`; never throws. */
+export function removeAutostart(opts = {}) {
+  const o = defaults(opts);
+  const file = autostartPath(o);
+  if (!file) return { removed: false, path: null };
+  if (o.platform === "darwin" && o.uid !== null) {
+    try {
+      o.run("launchctl", ["bootout", `gui/${o.uid}/${LABEL}`]);
+    } catch {
+      // not loaded
+    }
+  }
+  try {
+    fs.rmSync(file);
+    return { removed: true, path: file };
+  } catch {
+    return { removed: false, path: file };
+  }
+}
+
+/** Is the login item registered? */
+export function autostartInstalled(opts = {}) {
+  const file = autostartPath(opts);
+  return !!file && fs.existsSync(file);
+}
+
+/**
+ * A node path that survives an upgrade: the `node` on PATH when it is the very
+ * binary running now (Homebrew's /opt/homebrew/bin/node, not the versioned
+ * Cellar path the upgrade deletes), else this process's own.
+ */
+export function stableNodePath({ execPath = process.execPath, pathEnv = process.env.PATH ?? "", platform = process.platform } = {}) {
+  const real = (p) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return null;
+    }
+  };
+  const mine = real(execPath);
+  const exe = platform === "win32" ? "node.exe" : "node";
+  for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, exe);
+    if (mine && real(candidate) === mine) return candidate;
+  }
+  return execPath;
+}
+
+/**
+ * The `slidemind` entry script a login item can rely on: the one on PATH (the
+ * global install `setup` just made), else the running one — unless that lives
+ * in npx's throw-away cache. Null when there is none.
+ */
+export function stableScriptPath({ running, pathEnv = process.env.PATH ?? "", platform = process.platform } = {}) {
+  const names = platform === "win32" ? ["slidemind.cmd", "slidemind"] : ["slidemind"];
+  for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+    for (const n of names) {
+      const candidate = path.join(dir, n);
+      let target;
+      try {
+        target = fs.realpathSync(candidate);
+      } catch {
+        continue;
+      }
+      if (target.endsWith(`${path.sep}slidemind.mjs`)) return target;
+      // an npm .cmd/shell shim: the package's own entry sits next to the shim's target package
+      const pkgEntry = path.join(path.dirname(candidate), "node_modules", "slidemind", "bin", "slidemind.mjs");
+      if (fs.existsSync(pkgEntry)) return pkgEntry;
+    }
+  }
+  if (running && !/[\\/]_npx[\\/]/.test(running)) return running;
+  return null;
+}