@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/skills/lisa-secrets-access/scripts/bootstrap-store.mjs

@@ -0,0 +1,288 @@
+/**
+ * Store the one credential that unlocks the provider, on the machine that needs
+ * it.
+ *
+ * Reading it already existed; writing it did not, so every operator ran a
+ * platform-specific `security add-generic-password` copied from documentation.
+ * That is a command with a credential in it, typed by hand, on the one value
+ * whose compromise costs every other secret.
+ *
+ * **Two stores, because there is no third option.** macOS has a keychain that
+ * is encrypted at rest and unlocked with the login session. Linux has no
+ * equivalent that can be assumed present — libsecret needs a running daemon and
+ * a desktop session, which a server or a container does not have. So the
+ * fallback is a `0600` file under `$XDG_CONFIG_HOME`, which is the same
+ * protection the materialized secrets file already relies on. It is weaker than
+ * a keychain and it is stated as such, rather than pretending the two are equal.
+ * @module bootstrap-store
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The one grammar a bootstrap key may take: a single safe path segment.
+ *
+ * Named once and shared by the guard that enforces it on the way in
+ * ({@link assertKey}) and the filter that applies it on the way out
+ * ({@link listBootstrapFiles}). Two copies of this expression would eventually
+ * disagree, and the direction that matters is the lax one: a name accepted by
+ * the reader but rejected by the writer is a name this module never wrote.
+ */
+const KEY_GRAMMAR = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Where a file-backed bootstrap lives, for platforms with no keychain.
+ * @param {string} key Bootstrap variable name.
+ * @param {Record<string, string|undefined>} [env] Environment to read.
+ * @returns {string} Absolute path.
+ */
+export function bootstrapFile(key, env = process.env) {
+  const root = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+  return join(root, "lisa", "bootstrap", assertKey(key));
+}
+
+/**
+ * Reject a key that is not exactly one safe path segment.
+ *
+ * The key is joined onto a directory, and every entry point — store, clear and
+ * read — routes through that join. A `/` or a `..` in it escapes the bootstrap
+ * directory, so an unvalidated key can write, delete, or read an arbitrary file
+ * as the operator. Validating in `bootstrapFile` covers all three at once
+ * rather than trusting each caller to remember.
+ *
+ * Same guard `assertNamespace` applies to the namespace, and for the same
+ * reason. The character set is what a variable name can hold anyway, so nothing
+ * legitimate is refused.
+ * @param {string} key Candidate bootstrap variable name.
+ * @returns {string} The key, unchanged, when valid.
+ */
+export function assertKey(key) {
+  if (typeof key !== "string" || !KEY_GRAMMAR.test(key) || key === "..") {
+    throw new Error(
+      `bootstrap key must be one safe path segment, got ${JSON.stringify(key)}`
+    );
+  }
+  return key;
+}
+
+/**
+ * Quote a word for `security -i`, which tokenizes its stdin like a shell.
+ *
+ * A token is usually base64-ish and needs no quoting, but "usually" is not a
+ * property to rely on for a credential: an unquoted value containing a space
+ * would be parsed as two arguments and silently store only the first part.
+ * A newline is refused outright rather than escaped, because it terminates the
+ * command line and there is no quoting that survives it.
+ * @param {string} word Value to quote.
+ * @returns {string} A single quoted token.
+ */
+function quote(word) {
+  if (/[\n\r]/.test(word)) {
+    throw new Error("bootstrap value must not contain a newline");
+  }
+  return `"${String(word).replace(/(["\\])/g, "\\$1")}"`;
+}
+
+/**
+ * Which store this platform uses.
+ * @param {string} [platform] Platform name, injectable for tests.
+ * @returns {"keychain"|"file"} The store.
+ */
+export function storeKind(platform = process.platform) {
+  return platform === "darwin" ? "keychain" : "file";
+}
+
+/**
+ * Write the bootstrap where this machine's sessions will look for it.
+ *
+ * The value never reaches a command line on either path. The keychain path
+ * feeds `security -i` a command stream on **stdin**, because an argument is
+ * visible in `ps` to every process running as this user for as long as the call
+ * lasts. The file path writes and chmods a temporary before renaming, so the
+ * credential is never briefly world-readable on a filesystem where the default
+ * umask would have made it so.
+ * @param {string} key Bootstrap variable name.
+ * @param {string} value The token.
+ * @param {object} [deps] Injected seams, for tests.
+ * @returns {{kind: string, where: string}} Where it went.
+ */
+export function storeBootstrap(key, value, deps = {}) {
+  const kind = deps.kind ?? storeKind();
+  const env = deps.env ?? process.env;
+
+  if (kind === "keychain") {
+    const run = deps.run ?? execFileSync;
+    assertKey(key);
+    // `security -i` reads a COMMAND STREAM on stdin, which is what keeps the
+    // value out of `argv` — where `ps` would show it to every process running
+    // as this user for as long as the call lasts.
+    //
+    // The obvious `-w` with no argument does NOT read the password from stdin.
+    // It opens an interactive prompt on the terminal, and with stdin piped it
+    // stores an EMPTY value and exits 0 — verified against the real binary,
+    // which is how this shipped broken the first time: unit tests injected the
+    // runner and never executed it.
+    //
+    // `-U` updates in place; without it a second run fails with "already
+    // exists", making rotation — the common case — the broken one.
+    run("security", ["-i"], {
+      input: `add-generic-password -U -s ${quote(key)} -a ${quote(
+        env.USER ?? ""
+      )} -w ${quote(value)}\n`,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+    return { kind, where: `keychain (service ${key})` };
+  }
+
+  const path = deps.path ?? bootstrapFile(key, env);
+  const write = deps.write ?? writeFileSync;
+  const chmod = deps.chmod ?? chmodSync;
+  const rename = deps.rename ?? renameSync;
+  const makeDir = deps.mkdir ?? mkdirSync;
+
+  makeDir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.tmp`;
+  // mode on write applies only when the file is CREATED, so an existing
+  // temporary from a crashed run would keep its old permissions. chmod after
+  // writing is what makes 0600 true rather than usually true.
+  write(temporary, `${value}\n`, { mode: 0o600 });
+  chmod(temporary, 0o600);
+  rename(temporary, path);
+  return { kind, where: path };
+}
+
+/**
+ * Remove a stored bootstrap, so a rotation can be proven rather than assumed.
+ * @param {string} key Bootstrap variable name.
+ * @param {object} [deps] Injected seams, for tests.
+ */
+export function clearBootstrap(key, deps = {}) {
+  const kind = deps.kind ?? storeKind();
+  const env = deps.env ?? process.env;
+
+  if (kind === "keychain") {
+    const run = deps.run ?? execFileSync;
+    try {
+      run(
+        "security",
+        ["delete-generic-password", "-s", key, "-a", env.USER ?? ""],
+        {
+          stdio: "ignore",
+        }
+      );
+    } catch {
+      // Absent is the desired state, and `security` exits non-zero for it.
+    }
+    return;
+  }
+  const remove = deps.remove ?? rmSync;
+  remove(deps.path ?? bootstrapFile(key, env), { force: true });
+}
+
+/**
+ * Whether this machine already holds a bootstrap under that name.
+ *
+ * Asked so `environment local` can re-materialize after a rotation in the vault
+ * without demanding the token again — that is the common case, and prompting
+ * every time would make it the tedious one.
+ *
+ * Presence only. The value is never read here, because nothing about deciding
+ * whether to prompt needs it.
+ * @param {string} key Bootstrap variable name.
+ * @param {object} [deps] Injected seams, for tests.
+ * @returns {boolean} True when a value is stored.
+ */
+export function hasBootstrap(key, deps = {}) {
+  const kind = deps.kind ?? storeKind();
+  const env = deps.env ?? process.env;
+
+  if (kind === "keychain") {
+    const run = deps.run ?? execFileSync;
+    try {
+      run(
+        "security",
+        ["find-generic-password", "-s", assertKey(key), "-a", env.USER ?? ""],
+        { stdio: "ignore" }
+      );
+      return true;
+    } catch {
+      // probe-direction: fail-closed — false means "no bootstrap value proven
+      // present", which makes the setup flow ASK for one. A keychain that cannot
+      // be queried costs a redundant prompt, never a skipped bootstrap.
+      return false;
+    }
+  }
+  return (deps.exists ?? existsSync)(deps.path ?? bootstrapFile(key, env));
+}
+
+/**
+ * Read a file-backed bootstrap, treating absence as empty.
+ *
+ * The keychain reader lives beside the other provider concerns in
+ * `providers.mjs`; this is its counterpart for platforms without one.
+ * @param {string} key Bootstrap variable name.
+ * @param {Record<string, string|undefined>} [env] Environment to read.
+ * @returns {string} The value, or an empty string.
+ */
+export function readBootstrapFile(key, env = process.env) {
+  const path = bootstrapFile(key, env);
+  if (!existsSync(path)) return "";
+  return readFileSync(path, "utf8").trim();
+}
+
+/**
+ * Every file-backed bootstrap NAME this machine holds. Never a value.
+ *
+ * Exists so a failed lookup can say what is actually here instead of only what
+ * was missing. Those are different sentences: "no bootstrap credential is
+ * provisioned" and "one is provisioned under a different name" have different
+ * remedies, and a message that cannot tell them apart gets read as the first
+ * when it means the second (CodySwannGT/lisa#3555).
+ *
+ * Absence is empty, never an error. This runs on a path that is already
+ * failing, and a diagnostic that throws replaces the real message with its own.
+ *
+ * Two filters, and both are load-bearing because these names are rendered into
+ * an operator-facing message and into a `.lisa.config.json` snippet the
+ * operator is invited to paste:
+ *
+ * - **Grammar.** `readdirSync` returns whatever is in the directory. A name
+ *   outside {@link KEY_GRAMMAR} is not a key this module would ever have
+ *   written, and one carrying a quote or a newline would corrupt the suggested
+ *   JSON rather than merely look odd. The same grammar `assertKey` enforces on
+ *   the way in is applied on the way out.
+ * - **Dotfiles.** The reader is deliberately STRICTER than the writer here.
+ *   `KEY_GRAMMAR` permits a leading dot, so `assertKey(".DS_Store")` passes —
+ *   and macOS writes exactly that file into any directory it browses. Listing
+ *   it would offer the operator a credential named `.DS_Store`. Being stricter
+ *   on read is the safe direction: it can only omit a name, never invent one.
+ * - **Content.** An empty file is not a credential. Offering one sends the
+ *   operator to a store that will fail the same way a second time — and the
+ *   environment scan already refuses empty values, so listing empty FILES would
+ *   have made the two stores disagree about what counts as provisioned.
+ * @param {Record<string, string|undefined>} [env] Environment to read.
+ * @returns {string[]} Bootstrap names that hold a credential, sorted.
+ */
+export function listBootstrapFiles(env = process.env) {
+  try {
+    const root = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+    return readdirSync(join(root, "lisa", "bootstrap"))
+      .filter(name => KEY_GRAMMAR.test(name) && !name.startsWith("."))
+      .filter(name => readBootstrapFile(name, env) !== "")
+      .sort();
+  } catch {
+    return [];
+  }
+}

package/plugins/lisa-devin/skills/lisa-secrets-access/scripts/doctor-secrets.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * Health checks for a project's secrets configuration.
+ *
+ * The most valuable check here is the last one, and it is the reason this file
+ * exists. A value present in both the provider and a local copy is **not a
+ * duplicate** — it is two live credentials, one of which is untracked. Both
+ * authenticate, so the difference is invisible from either side, and "tidying
+ * up the duplicate" deletes a working credential that no record accounts for.
+ * That is not hypothetical; it is what prompted the single-store rule.
+ *
+ * Every check reports without printing a value. Where two copies must be
+ * compared, they are compared by digest.
+ *
+ * Usage:
+ *   doctor-secrets.mjs
+ * @module doctor-secrets
+ */
+
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+
+import { validateNote } from "./note-format.mjs";
+import { fetchAll, fetchRotatable } from "./providers.mjs";
+import { readMaterialized } from "./resolve-secret.mjs";
+import { readConfig } from "./surfaces.mjs";
+
+/**
+ * Build a collector so each run owns its findings.
+ *
+ * Module-level state would make the checks untestable in isolation and would
+ * leak findings between runs in any process that calls them twice.
+ * @returns {{findings: object[], report: Function}} A collector.
+ */
+export function collector() {
+  const findings = [];
+  return {
+    findings,
+    report: (level, name, message) => findings.push({ level, name, message }),
+  };
+}
+
+/**
+ * Digest a value so two copies can be compared without exposing either.
+ * @param {string} value Secret value.
+ * @returns {string} A short digest.
+ */
+function fingerprint(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+/**
+ * The value a proxied credential reads as instead of a usable token.
+ *
+ * Some surfaces keep a credential outside the sandbox entirely and substitute
+ * the real value at egress. The variable is then present and non-empty, which
+ * is exactly what makes it dangerous: a presence check passes, and only a
+ * consumer that reads the variable *itself* discovers it holds a placeholder.
+ */
+const PROXY_PLACEHOLDER = "proxy-injected";
+
+/**
+ * Assert every declared name actually resolves.
+ * @param {object} cfg Resolved configuration.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Map<string, string>} file Materialized view.
+ * @param {Function} report Finding collector.
+ */
+export function checkRequired(cfg, provider, file, report) {
+  for (const name of cfg.require ?? []) {
+    const fromEnv = (process.env[name] ?? "").trim();
+    const resolves = fromEnv || file.get(name) || provider.get(name)?.value;
+
+    if (!resolves) {
+      report(
+        "error",
+        name,
+        "declared in secrets.require but resolves nowhere — a startup error, " +
+          "not a late surprise"
+      );
+      continue;
+    }
+
+    // Reported separately from "resolves" because the two are not the same
+    // claim. A tool that authenticates through the proxy works; a script that
+    // reads this variable and puts it in an Authorization header sends the
+    // literal placeholder and gets a confusing auth failure far from here.
+    if (fromEnv === PROXY_PLACEHOLDER) {
+      report(
+        "warn",
+        name,
+        `reads as the literal string "${PROXY_PLACEHOLDER}" — the value is ` +
+          `substituted at egress and never enters this environment. Tools that ` +
+          `authenticate through the proxy work; anything reading this variable ` +
+          `directly gets the placeholder, not a credential`
+      );
+      continue;
+    }
+
+    report("ok", name, "resolves");
+  }
+}
+
+/**
+ * Assert every key is an exact environment-variable name.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Function} report Finding collector.
+ */
+export function checkNaming(provider, report) {
+  for (const name of provider.keys()) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      report(
+        "warn",
+        name,
+        "key is not UPPER_SNAKE_CASE, so it will not resolve for the " +
+          "environment variable of that name — lookup is exact, never fuzzy"
+      );
+    }
+  }
+}
+
+/**
+ * Assert every secret carries a usage note in the documented format.
+ *
+ * This blocks rather than warns, and the promotion is the point. The contract
+ * has always said the note "must exist and be well-formed", enforced statically
+ * by `doctor` — but a warning enforces nothing, so a vault of empty notes
+ * reported clean and stayed empty. A check that never fails is a check nobody
+ * acts on.
+ *
+ * The grammar lives in `note-format.mjs` so this and `resolve-secret.mjs verify`
+ * cannot disagree about what a well-formed note is.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Function} report Finding collector.
+ */
+export function checkNotes(provider, report) {
+  for (const [name, entry] of provider) {
+    for (const defect of validateNote(entry?.note)) {
+      report(defect.level, name, defect.message);
+    }
+  }
+}
+
+/**
+ * Assert every rotating credential could persist its replacement.
+ * @param {object} cfg Resolved configuration.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Function} report Finding collector.
+ */
+export function checkRotating(cfg, provider, report) {
+  for (const name of cfg.rotating ?? []) {
+    if (!cfg.bootstrap?.key) {
+      report(
+        "error",
+        name,
+        "is declared rotating but the lane has no bootstrap, so a replacement " +
+          "could not be written back. Using it once would strand it"
+      );
+      continue;
+    }
+    if (!provider.get(name)?.id) {
+      report(
+        "error",
+        name,
+        "is declared rotating but has no provider identifier to write back to"
+      );
+      continue;
+    }
+    report("ok", name, "rotating, with a write path");
+  }
+}
+
+/**
+ * Detect the same credential living in more than one store.
+ *
+ * Two different values under one name are two live credentials, not a stale
+ * copy — treat it as stop-and-ask rather than something to adjudicate. Deleting
+ * the one you cannot verify leaves a working credential recorded nowhere.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Map<string, string>} file Materialized view.
+ * @param {Function} report Finding collector.
+ */
+export function checkTwoStores(provider, file, report) {
+  for (const [name, value] of file) {
+    const fromProvider = provider.get(name)?.value;
+    if (!fromProvider) continue;
+    if (fromProvider === value) {
+      report(
+        "warn",
+        name,
+        "exists in both the provider and a local copy. Same value today, but " +
+          "two stores drift; the local copy should be re-materialized, never edited"
+      );
+      continue;
+    }
+    report(
+      "error",
+      name,
+      `differs between the provider (${fingerprint(fromProvider)}) and the ` +
+        `local copy (${fingerprint(value)}). These are TWO LIVE CREDENTIALS, ` +
+        `not a duplicate. Stop and ask — deleting the one you cannot verify ` +
+        `leaves a working credential that no record accounts for`
+    );
+  }
+}
+
+function main() {
+  const cfg = readConfig();
+
+  if (cfg.provider === "env") {
+    console.log(
+      "secrets: no credentials manager configured (provider: env).\n" +
+        "  This is supported — the environment is the provider. A manager is the\n" +
+        "  preferred path because it gives one store, rotation, and an audit trail,\n" +
+        "  but it is never required. Configure one with secrets.provider when ready."
+    );
+    return;
+  }
+
+  const provider = fetchAll(cfg);
+  const file = readMaterialized(cfg);
+
+  console.log(`secrets: provider ${cfg.provider}, surface ${cfg.surface}`);
+  const { findings, report } = collector();
+  checkRequired(cfg, provider, file, report);
+  checkNaming(provider, report);
+  checkNotes(provider, report);
+  checkRotating(cfg, fetchRotatable(cfg), report);
+  checkTwoStores(provider, file, report);
+
+  const order = { error: 0, warn: 1, ok: 2 };
+  findings.sort((a, b) => order[a.level] - order[b.level]);
+  for (const f of findings) {
+    console.log(
+      `  ${f.level.toUpperCase().padEnd(5)} ${f.name.padEnd(28)} ${f.message}`
+    );
+  }
+
+  const errors = findings.filter(f => f.level === "error").length;
+  if (errors) throw new Error(`${errors} secrets configuration error(s)`);
+}
+
+/**
+ * Whether this module is the one node was asked to run.
+ *
+ * Both sides are realpath'd: a raw URL comparison answers "no" through a
+ * symlinked checkout, a git worktree, or a /tmp path on macOS, so the module
+ * loads, runs nothing and exits 0 — a silent no-op that reads as success.
+ *
+ * A local copy rather than an import: plugin payload scripts ship standalone,
+ * with no `lib/` sibling to import from once installed.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa-devin/skills/lisa-secrets-access/scripts/envfile.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * The `secrets.env` format: writer and reader, kept together.
+ *
+ * The file has two consumers with different needs. A shell sources it, so it
+ * must be valid POSIX with every value quoted. The resolver reads it back, so
+ * the quoting must be exactly reversible. Those two requirements only stay
+ * consistent if the pair lives in one module — a writer and a parser that drift
+ * apart corrupt any value containing a quote, and do it silently.
+ * @module envfile
+ */
+
+export { materializedOwnersMatch } from "../../lisa-setup-remote-env/assets/materialized-env-authority.mjs";
+
+/**
+ * POSIX single-quote a value so a shell reproduces it byte for byte.
+ *
+ * Single quotes suppress every expansion, so the only character needing care is
+ * the quote itself: close the string, emit an escaped quote, reopen.
+ * @param {string} value Raw value.
+ * @returns {string} A single-quoted shell token.
+ */
+export function quote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Render selected secrets as a sourceable environment file.
+ * @param {Map<string, {value: string}>} selected Secrets by exact name.
+ * @returns {string} File contents, newline-terminated.
+ */
+export function renderEnv(selected) {
+  const lines = [
+    "# Generated by lisa-secrets-access. Contains secret values.",
+    "# Do not print, inspect, summarize, commit, or copy this file.",
+  ];
+  for (const key of [...selected.keys()].sort()) {
+    lines.push(`export ${key}=${quote(selected.get(key).value)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Parse a file produced by {@link renderEnv} back into values.
+ *
+ * Deliberately strict: it understands only the shape this module writes. A line
+ * it does not recognise is skipped rather than guessed at, because a partial
+ * parse that yields a truncated secret is worse than one that yields nothing.
+ * @param {string} text File contents.
+ * @returns {Map<string, string>} Values by exact name.
+ */
+export function parseEnv(text) {
+  const out = new Map();
+  for (const line of text.split("\n")) {
+    const match = /^export ([A-Za-z_][A-Za-z0-9_]*)='(.*)'$/.exec(line);
+    if (!match) continue;
+    out.set(match[1], match[2].replaceAll(`'\\''`, "'"));
+  }
+  return out;
+}
+
+/**
+ * Render usage notes with every value intentionally omitted.
+ *
+ * The separation is the point: an agent reading a note must have no path to a
+ * value, so the note file is a different file with a different reader.
+ * @param {Map<string, {note: string}>} selected Secrets by exact name.
+ * @returns {string} JSON contents, newline-terminated.
+ */
+export function renderNotes(selected) {
+  const secrets = {};
+  for (const key of [...selected.keys()].sort()) {
+    const note = selected.get(key).note ?? "";
+    if (typeof note !== "string") {
+      throw new Error(`secret note is not a string: ${key}`);
+    }
+    secrets[key] = note;
+  }
+  return `${JSON.stringify({ schemaVersion: 1, secrets }, null, 2)}\n`;
+}