@capacms/cli 0.0.0-stage → 0.1.0

package/lib/credentials.mjs

@@ -0,0 +1,450 @@
+/**
+ * credentials.mjs — where `capa login` keeps a key, and how every other
+ * command finds it again.
+ *
+ * Two files and one secret store:
+ *
+ *   <config dir>/config.json   the profiles: one per key, with the project it
+ *                              reaches, its environment and the API address.
+ *                              No secret is ever in it.
+ *   the secret store           the key itself, under service "capa-cli" and
+ *                              the profile's name:
+ *                                macOS   the login keychain (`security`)
+ *                                Linux   the Secret Service (`secret-tool`),
+ *                                        where a session bus answers
+ *                                else    <config dir>/secrets.json, mode 0600
+ *
+ * The config dir is CAPA_CONFIG_DIR, else $XDG_CONFIG_HOME/capa, else
+ * ~/.config/capa. CAPA_CREDENTIAL_STORE=file or =keychain picks the store, and
+ * CAPA_KEYCHAIN names a keychain file to use instead of the login keychain
+ * (the tests make a throwaway one, so they never touch a person's own). It
+ * must exist: `security` given a missing one writes to the login keychain.
+ * Every change to config.json or secrets.json holds <config dir>/capa.lock,
+ * so two logins at once both keep their profile.
+ *
+ * THE SECRET NEVER GOES IN ARGV. A process's arguments are readable by every
+ * user on the machine (`ps`), so `security add-generic-password -w <key>`
+ * would publish the key for as long as it runs. The key is written to
+ * `security -i` on stdin instead, and to `secret-tool store` on stdin, which
+ * is how that tool reads a secret anyway. `security -i` exits 0 whatever its
+ * commands did, so every write is read back before it counts as saved.
+ *
+ * A profile is a credential RECORD with a `type`. Today every record is
+ * `"api_key"`; a sign-in that hands back tokens (the hosted MCP lane's
+ * loopback OAuth) is a second type beside it, read by `secretFor` and nothing
+ * else, so no command has to change when it lands.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const SERVICE = "capa-cli";
+export const CONFIG_VERSION = 1;
+
+/** A process runner: `{ status, stdout, stderr, error }`, as `spawnSync` answers. */
+export function systemRunner(command, args, { input } = {}) {
+  const out = spawnSync(command, args, { input, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 15_000 });
+  return { status: out.status, stdout: out.stdout ?? "", stderr: out.stderr ?? "", error: out.error ?? null };
+}
+
+export function configDir(env = process.env) {
+  if (env.CAPA_CONFIG_DIR) return path.resolve(env.CAPA_CONFIG_DIR);
+  const base = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
+  return path.join(base, "capa");
+}
+
+/**
+ * How old a lock is before it counts as left by a capa that crashed, and how
+ * long a second capa waits for one. createCredentials({ lockTimes }) takes
+ * other values, `{ staleMs, waitMs }`, so a test of a wait is not 45 s long.
+ */
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 45_000;
+const held = new Set();
+const pause = new Int32Array(new SharedArrayBuffer(4));
+
+/** Is process `pid` running? EPERM means it is, as another user. */
+function running(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+/** The lock file's text, or null when there is none. */
+function lockText(lock) {
+  try {
+    return fs.readFileSync(lock, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** The lock's text and age, read from one open file so the two belong together; null when there is none. */
+function inspectLock(lock) {
+  let fd;
+  try {
+    fd = fs.openSync(lock, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const age = Date.now() - fs.fstatSync(fd).mtimeMs;
+    return { age, text: fs.readFileSync(fd, "utf8") };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** Is this lock left by a capa that is gone: older than LOCK_STALE_MS, its pid not running? */
+const abandoned = (seen, staleMs) => seen !== null && seen.age > staleMs && !running(Number.parseInt(seen.text, 10));
+
+/**
+ * Is this takeover guard left by a waiter that died holding it? A guard is
+ * held only while its waiter looks at the lock once, so one older than
+ * LOCK_STALE_MS is abandoned whatever its pid says: that pid may be another
+ * process's by now, and a guard kept by a reused pid used to block every
+ * waiter for good.
+ */
+const guardAbandoned = (seen, staleMs) => seen !== null && seen.age > staleMs;
+
+/**
+ * Removes `lock` if it is abandoned, one waiter at a time. Two waiters can
+ * judge the same lock abandoned; the first removes it and makes its own, and
+ * the second must not then remove THAT. Checking and then removing leaves a
+ * moment between the two (renaming the lock aside and linking a live one
+ * back leaves one too: with 8 waiters, 9 of 2,400 profiles were still
+ * lost). So a takeover holds `<lock>.takeover`, made with O_EXCL, and looks
+ * again while it holds it: while the abandoned lock is there nobody can make
+ * a new one, and no other waiter can remove it, so what it sees is what it
+ * removes. A waiter that finds the guard taken leaves it to the other, and
+ * waits as it would for the lock. A guard left by a crash is cleared once it
+ * is abandoned (see guardAbandoned).
+ *
+ * KNOWN GAP: clearing an abandoned guard is itself check-then-remove. Two
+ * waiters that both judge the same dead guard abandoned can each remove one,
+ * the second removing the guard the first has just made, and then both hold
+ * a guard at once. It needs a waiter to die inside the microseconds it holds
+ * the guard, and then costs at most the one race the guard exists to stop;
+ * a guard for the guard would only move it. Left as is on purpose.
+ */
+function takeOver(lock, staleMs) {
+  const guard = `${lock}.takeover`;
+  try {
+    fs.writeFileSync(guard, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    if (guardAbandoned(inspectLock(guard), staleMs)) fs.rmSync(guard, { force: true });
+    return;
+  }
+  try {
+    if (abandoned(inspectLock(lock), staleMs)) fs.rmSync(lock, { force: true });
+  } finally {
+    fs.rmSync(guard, { force: true });
+  }
+}
+
+/**
+ * Runs `fn` holding `<dir>/capa.lock`, so two capa commands saving at once
+ * (two logins in two terminals, a script logging in several profiles) each
+ * read what the other wrote: config.json and secrets.json are each read,
+ * changed and written whole, and without the lock the later write drops the
+ * earlier one's profile. The lock is a file made with O_EXCL, holding the
+ * holder's pid and a nonce. A holder that crashed leaves one behind, which is
+ * taken over once it is LOCK_STALE_MS old AND its pid is not running: a login
+ * waiting on a keychain dialog holds it for as long as the dialog is open,
+ * and is waited for. A release removes the lock only while it still holds
+ * this call's pid and nonce. Re-entrant within a process, since a login
+ * writes both files.
+ *
+ * Every pass that ends with the lock still there pauses and counts against
+ * LOCK_WAIT_MS, a takeover that could not act included: a waiter that found
+ * the guard taken used to go straight round again, a full core spent for as
+ * long as the guard stayed.
+ */
+function withLock(dir, fn, { staleMs = LOCK_STALE_MS, waitMs = LOCK_WAIT_MS } = {}) {
+  const lock = path.join(dir, "capa.lock");
+  if (held.has(lock)) return fn();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const mine = `${process.pid} ${crypto.randomBytes(8).toString("hex")}\n`;
+  const started = Date.now();
+  for (;;) {
+    try {
+      fs.writeFileSync(lock, mine, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    if (abandoned(inspectLock(lock), staleMs)) takeOver(lock, staleMs);
+    // Released while we looked, or taken over: try again at once. lstat, not
+    // existsSync: a symlink there, dangling or not, fails O_EXCL with EEXIST,
+    // and existsSync follows a dangling one, finds nothing and spun the loop.
+    if (!fs.lstatSync(lock, { throwIfNoEntry: false })) continue;
+    if (Date.now() - started > waitMs) {
+      throw new Error(`Another capa command is saving to ${dir} and has not finished. Try again; if no capa is running, delete ${lock} and ${lock}.takeover, whichever is there.`);
+    }
+    Atomics.wait(pause, 0, 0, 5 + Math.floor(Math.random() * 20));
+  }
+  held.add(lock);
+  try {
+    return fn();
+  } finally {
+    held.delete(lock);
+    if (lockText(lock) === mine) fs.rmSync(lock, { force: true });
+  }
+}
+
+/** Writes a file another user can never read, and never half-written: a temp file in the same directory, renamed over. */
+function writePrivate(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, text, { mode: 0o600 });
+  fs.renameSync(temp, file);
+  fs.chmodSync(file, 0o600);
+}
+
+function readJson(file, fallback) {
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback;
+    throw error;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${file} is not JSON. Fix it by hand, or delete it and run capa login again.`);
+  }
+}
+
+/**
+ * A key that can be written into a `security -i` command line safely: printable
+ * ASCII with no quote, backslash or space. Every key Capa mints is letters,
+ * digits and underscores; anything else is refused rather than escaped.
+ */
+const SAFE_SECRET = /^[\x21-\x7e]+$/;
+const isSafeSecret = (secret) => SAFE_SECRET.test(secret) && !/["'\\]/.test(secret);
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * Whether `keychain` names a keychain file that is there: the path as given,
+ * or a name under ~/Library/Keychains (with or without `-db`), which is where
+ * `security` looks for a bare name.
+ */
+function keychainExists(keychain, home) {
+  const dir = path.join(home, "Library", "Keychains");
+  return [keychain, path.join(dir, keychain), path.join(dir, `${keychain}-db`)].some((file) => {
+    try {
+      return fs.statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * The macOS keychain, through `security`. `keychain` is a keychain file, or
+ * null for the default search list. A keychain that is not there is refused
+ * before `security` runs: given a missing keychain, `add-generic-password`
+ * writes to the login keychain instead and `security -i` still exits 0, and
+ * the read-back finds it there through the search list.
+ */
+export function keychainStore(run, keychain = null, home = os.homedir()) {
+  const target = keychain ? [keychain] : [];
+  const quoted = keychain ? ` "${keychain}"` : "";
+  const present = () => {
+    if (keychain && !keychainExists(keychain, home)) {
+      throw Object.assign(new Error(`CAPA_KEYCHAIN names ${keychain}, which does not exist. Create it (security create-keychain), fix the path, or unset CAPA_KEYCHAIN to use the login keychain.`), { exitCode: 3 });
+    }
+  };
+  const read = (account) => {
+    present();
+    const out = run("security", ["find-generic-password", "-s", SERVICE, "-a", account, "-w", ...target]);
+    if (out.error) throw new Error(`could not run security: ${out.error.message}`);
+    return out.status === 0 ? out.stdout.replace(/\n$/, "") : null;
+  };
+  return {
+    kind: "keychain",
+    label: keychain ? `the keychain ${keychain}` : "the macOS keychain",
+    write(account, secret) {
+      if (!isSafeSecret(secret)) throw new Error("That key has characters no Capa key has (a space, a quote or a backslash). Check what was pasted.");
+      if (keychain && /["\\\n]/.test(keychain)) throw new Error("CAPA_KEYCHAIN has a quote, a backslash or a newline in it.");
+      present();
+      const line = `add-generic-password -U -s "${SERVICE}" -a "${account}" -l "Capa CLI (${account})" -w "${secret}"${quoted}\n`;
+      const out = run("security", ["-i"], { input: line });
+      if (out.error) throw new Error(`could not run security: ${out.error.message}`);
+      if (read(account) !== secret) throw new Error("The keychain did not keep the key (security answered, but reading it back failed). Use CAPA_CREDENTIAL_STORE=file to keep it in a file instead.");
+    },
+    read,
+    remove(account) {
+      present();
+      run("security", ["delete-generic-password", "-s", SERVICE, "-a", account, ...target]);
+    },
+  };
+}
+
+/** The Secret Service on Linux, through `secret-tool`. */
+export function secretToolStore(run) {
+  return {
+    kind: "secret-service",
+    label: "the Secret Service keyring",
+    write(account, secret) {
+      const out = run("secret-tool", ["store", "--label", `Capa CLI (${account})`, "service", SERVICE, "account", account], { input: secret });
+      if (out.error || out.status !== 0) throw new Error(`secret-tool could not store the key: ${(out.stderr || out.error?.message || "").trim()}`);
+      if (this.read(account) !== secret) throw new Error("The keyring did not keep the key. Use CAPA_CREDENTIAL_STORE=file to keep it in a file instead.");
+    },
+    read(account) {
+      const out = run("secret-tool", ["lookup", "service", SERVICE, "account", account]);
+      return out.status === 0 && out.stdout ? out.stdout.replace(/\n$/, "") : null;
+    },
+    remove(account) {
+      run("secret-tool", ["clear", "service", SERVICE, "account", account]);
+    },
+  };
+}
+
+/** A file only its owner can read: the store where there is no keychain. */
+export function fileStore(dir) {
+  const file = path.join(dir, "secrets.json");
+  const load = () => readJson(file, {});
+  return {
+    kind: "file",
+    label: file,
+    write(account, secret) {
+      withLock(dir, () => writePrivate(file, `${JSON.stringify({ ...load(), [account]: secret }, null, 2)}\n`));
+    },
+    read(account) {
+      const value = load()[account];
+      return typeof value === "string" ? value : null;
+    },
+    remove(account) {
+      withLock(dir, () => {
+        const all = load();
+        if (!(account in all)) return;
+        delete all[account];
+        if (Object.keys(all).length) writePrivate(file, `${JSON.stringify(all, null, 2)}\n`);
+        else fs.rmSync(file, { force: true });
+      });
+    },
+  };
+}
+
+/** The store a new key goes to: what CAPA_CREDENTIAL_STORE asks for, else the platform's keychain where it works, else a file. */
+export function chooseStore({ env = process.env, platform = process.platform, run = systemRunner } = {}) {
+  const dir = configDir(env);
+  const wanted = (env.CAPA_CREDENTIAL_STORE || "").trim();
+  if (wanted && wanted !== "file" && wanted !== "keychain") {
+    throw new Error(`CAPA_CREDENTIAL_STORE is ${JSON.stringify(wanted)}; it takes file or keychain.`);
+  }
+  if (wanted === "file") return fileStore(dir);
+  if (platform === "darwin") return keychainStore(run, env.CAPA_KEYCHAIN || null, env.HOME || os.homedir());
+  if (platform === "linux" && env.DBUS_SESSION_BUS_ADDRESS) {
+    const probe = run("secret-tool", ["lookup", "service", SERVICE, "account", "__capa_probe__"]);
+    if (!probe.error) return secretToolStore(run);
+  }
+  if (wanted === "keychain") throw new Error("CAPA_CREDENTIAL_STORE=keychain, but this machine has no keychain the CLI can use (macOS keychain, or secret-tool with a session bus).");
+  return fileStore(dir);
+}
+
+/** The store a saved profile names, so a key is read back from where it was written. */
+function storeNamed(kind, { env, platform, run }) {
+  const dir = configDir(env);
+  if (kind === "file") return fileStore(dir);
+  if (kind === "keychain") return keychainStore(run, env.CAPA_KEYCHAIN || null, env.HOME || os.homedir());
+  if (kind === "secret-service") return secretToolStore(run);
+  throw new Error(`a profile names the store ${JSON.stringify(kind)}, which this version of capa does not know. Run capa login again.`);
+}
+
+/**
+ * The profiles and their keys. Everything here is synchronous and local: no
+ * call reaches Capa, so a test can drive it with a fake runner and a temp dir.
+ */
+export function createCredentials({ env = process.env, platform = process.platform, run = systemRunner, lockTimes = {} } = {}) {
+  const dir = configDir(env);
+  const file = path.join(dir, "config.json");
+  const load = () => {
+    const config = readJson(file, { version: CONFIG_VERSION, current: null, profiles: {} });
+    if (!config.profiles || typeof config.profiles !== "object") config.profiles = {};
+    return config;
+  };
+  const save = (config) => writePrivate(file, `${JSON.stringify(config, null, 2)}\n`);
+  // The file store's own locking runs inside these, so it re-enters and takes no times of its own.
+  const locked = (fn) => withLock(dir, fn, lockTimes);
+
+  return {
+    dir,
+    file,
+    list() {
+      const config = load();
+      return { current: config.current ?? null, profiles: Object.entries(config.profiles).map(([name, meta]) => ({ name, ...meta })) };
+    },
+    /** `{ name, meta }` for `name`, else CAPA_PROFILE, else the current one; null when there is none. */
+    active(name = null) {
+      const config = load();
+      const wanted = name || env.CAPA_PROFILE || config.current;
+      if (!wanted) return null;
+      const meta = config.profiles[wanted];
+      if (!meta) {
+        if (name || env.CAPA_PROFILE) {
+          const known = Object.keys(config.profiles);
+          throw Object.assign(new Error(`No profile ${JSON.stringify(wanted)}.${known.length ? ` Saved: ${known.join(", ")}.` : " Nothing is saved yet: run capa login."}`), { exitCode: 3 });
+        }
+        return null;
+      }
+      return { name: wanted, meta };
+    },
+    secretFor(profile) {
+      if (profile.meta.type !== "api_key") {
+        throw Object.assign(new Error(`Profile ${profile.name} holds a sign-in of type ${profile.meta.type}, which this version of capa cannot use. Update @capacms/cli, or run capa login with a key.`), { exitCode: 3 });
+      }
+      return storeNamed(profile.meta.store, { env, platform, run }).read(profile.name);
+    },
+    /** Saves a key under `name` and makes it current. Answers where the key went. */
+    add(name, meta, secret) {
+      if (!SAFE_NAME.test(name)) throw Object.assign(new Error(`${JSON.stringify(name)} cannot name a profile: use letters, digits, dots, dashes and underscores.`), { exitCode: 2 });
+      const store = chooseStore({ env, platform, run });
+      return locked(() => {
+        const config = load();
+        const before = config.profiles[name];
+        store.write(name, secret);
+        // A profile moving stores leaves no copy behind in the old one.
+        if (before && before.store !== store.kind) storeNamed(before.store, { env, platform, run }).remove(name);
+        config.profiles[name] = { type: "api_key", ...meta, store: store.kind, savedAt: new Date().toISOString() };
+        config.current = name;
+        config.version = CONFIG_VERSION;
+        save(config);
+        return { store: store.kind, where: store.label };
+      });
+    },
+    use(name) {
+      locked(() => {
+        const config = load();
+        if (!config.profiles[name]) {
+          const known = Object.keys(config.profiles);
+          throw Object.assign(new Error(`No profile ${JSON.stringify(name)}.${known.length ? ` Saved: ${known.join(", ")}.` : ""}`), { exitCode: 3 });
+        }
+        config.current = name;
+        save(config);
+      });
+    },
+    /** Forgets a profile and deletes its key. Answers the profile, or null when there was none. */
+    remove(name) {
+      return locked(() => {
+        const config = load();
+        const meta = config.profiles[name];
+        if (!meta) return null;
+        storeNamed(meta.store, { env, platform, run }).remove(name);
+        delete config.profiles[name];
+        if (config.current === name) config.current = Object.keys(config.profiles)[0] ?? null;
+        save(config);
+        return { name, ...meta };
+      });
+    },
+  };
+}

package/lib/diff.mjs

@@ -0,0 +1,45 @@
+/**
+ * diff.mjs — the change `capa init` is about to make, as a person reads one:
+ * removed lines with `-`, added lines with `+`, and two lines of context
+ * around each change. Config files are small, so a plain longest-common-
+ * subsequence table is fast enough and needs no library.
+ */
+export function lineDiff(before, after, { context = 2 } = {}) {
+  const a = before === "" ? [] : before.replace(/\n$/, "").split("\n");
+  const b = after === "" ? [] : after.replace(/\n$/, "").split("\n");
+  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      ops.push({ op: " ", line: a[i] });
+      i++;
+      j++;
+    } else if (j < b.length && (i === a.length || lcs[i][j + 1] >= lcs[i + 1][j])) {
+      ops.push({ op: "+", line: b[j] });
+      j++;
+    } else {
+      ops.push({ op: "-", line: a[i] });
+      i++;
+    }
+  }
+  const keep = ops.map((o, k) => o.op !== " " || ops.slice(Math.max(0, k - context), k + context + 1).some((n) => n.op !== " "));
+  const out = [];
+  let skipped = false;
+  ops.forEach((o, k) => {
+    if (keep[k]) {
+      if (skipped && out.length) out.push("  ...");
+      skipped = false;
+      out.push(`${o.op} ${o.line}`);
+    } else {
+      skipped = true;
+    }
+  });
+  return out.join("\n");
+}