@codyswann/lisa 2.316.2 → 2.317.0

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

@@ -0,0 +1,217 @@
+#!/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 { fetchAll } 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);
+}
+
+/**
+ * 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 resolves =
+      (process.env[name] ?? "").trim() ||
+      file.get(name) ||
+      provider.get(name)?.value;
+    if (resolves) report("ok", name, "resolves");
+    else
+      report(
+        "error",
+        name,
+        "declared in secrets.require but resolves nowhere — a startup error, " +
+          "not a late surprise"
+      );
+  }
+}
+
+/**
+ * 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.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Function} report Finding collector.
+ */
+export function checkNotes(provider, report) {
+  for (const [name, entry] of provider) {
+    if (!entry.note?.trim()) {
+      report(
+        "warn",
+        name,
+        "has no usage note. An agent cannot learn this credential's scope " +
+          "without one, and inferring it from the name is exactly the guess " +
+          "that writes to the wrong system"
+      );
+    }
+  }
+}
+
+/**
+ * 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, provider, 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)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,78 @@
+#!/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
+ */
+
+/**
+ * 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`;
+}

package/plugins/lisa-cursor/skills/lisa-secrets-access/scripts/materialize-secrets.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Write the provider's current view to the two files a materializing surface
+ * reads.
+ *
+ * Only surfaces that cannot read through live use this. A remote agent
+ * container prepares itself during setup — before any task exists, and often
+ * before network policy would permit a provider call from the task itself — so
+ * files written at that moment are the only channel available. Everywhere else
+ * this is forbidden, because a value on disk is a copy that can drift and leak.
+ *
+ * Both files are written atomically from one provider response, so values and
+ * notes always describe the same revision. A rename within the destination
+ * directory is atomic on the same filesystem; a temporary file elsewhere would
+ * not be.
+ *
+ * Usage:
+ *   materialize-secrets.mjs [--dry-run]
+ * @module materialize-secrets
+ */
+
+import {
+  chmodSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+
+import { renderEnv, renderNotes } from "./envfile.mjs";
+import { fetchAll } from "./providers.mjs";
+import { materializedPaths, readConfig } from "./surfaces.mjs";
+
+/**
+ * Write one file to a temporary sibling, then move it into place.
+ *
+ * The mode is set before the rename so the file is never briefly readable by
+ * anyone else, and the temporary sibling is removed on any failure so a partial
+ * write cannot be mistaken for a complete one.
+ * @param {string} destination Final path.
+ * @param {string} contents File body.
+ */
+function writeAtomic(destination, contents) {
+  const temporary = `${destination}.tmp-${process.pid}`;
+  try {
+    writeFileSync(temporary, contents, { mode: 0o600 });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, destination);
+  } catch (err) {
+    rmSync(temporary, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * Materialize the configured provider view for the current surface.
+ * @param {object} [cfg] Resolved configuration.
+ * @returns {{count: number, dir: string}} What was written, and where.
+ */
+export function materialize(cfg = readConfig()) {
+  if (!cfg.capabilities.mayWriteValues) {
+    throw new Error(
+      `surface "${cfg.surface}" may not write secret values to disk.\n` +
+        `It can read through to the provider, so a copy on disk would add drift ` +
+        `and exposure without adding capability.`
+    );
+  }
+
+  const selected = fetchAll(cfg);
+  if (!selected.size) {
+    throw new Error(
+      "no exportable secrets matched the configured boundary.\n" +
+        "Check the machine account's project grants and any narrowing filters."
+    );
+  }
+
+  const { dir, valuesFile, notesFile } = materializedPaths(cfg.namespace);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  writeAtomic(valuesFile, renderEnv(selected));
+  writeAtomic(notesFile, renderNotes(selected));
+  return { count: selected.size, dir };
+}
+
+function main() {
+  const cfg = readConfig();
+  if (process.argv.includes("--dry-run")) {
+    const selected = fetchAll(cfg);
+    const { dir } = materializedPaths(cfg.namespace);
+    console.log(`would write ${selected.size} secret(s) to ${dir}`);
+    console.log([...selected.keys()].sort().join("\n"));
+    return;
+  }
+  const { count, dir } = materialize(cfg);
+  console.log(`materialized ${count} secret(s) and their notes into ${dir}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa-cursor/skills/lisa-secrets-access/scripts/providers.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * Provider reads and boundary enforcement for `lisa-secrets-access`.
+ *
+ * Retrieval and selection are separated deliberately. `fetchRaw` is the only
+ * function that touches a provider; everything downstream operates on plain
+ * rows, which is what makes the boundary rules testable with synthetic data and
+ * without granting a test process access to any real secret.
+ * @module providers
+ */
+
+import { execFileSync } from "node:child_process";
+
+/**
+ * A provider key becomes a shell variable name on materializing surfaces, so
+ * only names valid in every POSIX-like shell are accepted. Anything else stays
+ * in the provider and is intentionally not exported.
+ */
+export const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The provider entry holding rotation leases.
+ *
+ * Leases live in the provider because it is the only substrate every surface
+ * shares — a CI concurrency group and a laptop lockfile cannot see each other,
+ * but both can see this. It is coordination state rather than a credential, so
+ * it is excluded from every selection: nothing should resolve or materialize it.
+ */
+export const LEASE_KEY = "LISA_ROTATION_LEASES";
+
+/**
+ * Obtain the one credential that unlocks the provider.
+ *
+ * Walks `sources` in order, environment first, so a CI run where the pipeline
+ * injects the bootstrap never reaches for a local store. This is the only
+ * credential permitted in an OS keychain — it is a bootstrap, not a cached copy
+ * of anything downstream.
+ * @param {{sources: string[], key: string|null}} bootstrap Bootstrap config.
+ * @returns {string|null} The token, or null when the provider needs none.
+ */
+export function bootstrapToken(bootstrap) {
+  if (!bootstrap.key) return null;
+  for (const source of bootstrap.sources) {
+    const found =
+      source === "env"
+        ? (process.env[bootstrap.key] ?? "").trim()
+        : source === "keychain"
+          ? fromKeychain(bootstrap.key)
+          : "";
+    if (found) return found;
+  }
+  throw new Error(
+    `${bootstrap.key} not found in: ${bootstrap.sources.join(", ")}.\n` +
+      `It is the bootstrap credential — without it no other secret can be read.`
+  );
+}
+
+/**
+ * Read one value from the macOS keychain, treating absence as empty.
+ * @param {string} key Keychain service name.
+ * @returns {string} The value, or an empty string when unavailable.
+ */
+function fromKeychain(key) {
+  if (process.platform !== "darwin") return "";
+  try {
+    return execFileSync(
+      "security",
+      ["find-generic-password", "-s", key, "-a", process.env.USER ?? "", "-w"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    ).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Read every secret the provider grants, as unfiltered rows.
+ *
+ * Deliberately reads all rather than one: the provider already scopes what this
+ * caller may see, so the set it returns *is* the permitted set. Restating that
+ * as a list in config would duplicate a boundary the provider already enforces.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Array<{key: string, value: string, note: string, projectId: string|null}>} Rows.
+ */
+export function fetchRaw(cfg) {
+  const env = { ...process.env };
+  const token = bootstrapToken(cfg.bootstrap);
+  if (cfg.bootstrap.key && token) env[cfg.bootstrap.key] = token;
+
+  if (cfg.provider === "env") {
+    return Object.entries(process.env)
+      .filter(([k]) => /^[A-Z][A-Z0-9_]*$/.test(k))
+      .map(([key, value]) => ({
+        key,
+        value: value ?? "",
+        note: "",
+        projectId: null,
+      }));
+  }
+
+  if (cfg.provider === "bitwarden") {
+    const raw = run("bws", ["secret", "list", "--output", "json"], env);
+    return JSON.parse(raw || "[]").map(s => ({
+      key: s.key,
+      value: s.value,
+      note: s.note ?? "",
+      projectId: s.projectId ?? null,
+      id: s.id ?? null,
+    }));
+  }
+
+  if (cfg.provider === "doppler") {
+    const args = ["secrets", "download", "--no-file", "--format", "json"];
+    const raw = run("doppler", args, env);
+    return Object.entries(JSON.parse(raw || "{}")).map(([key, value]) => ({
+      key,
+      value: String(value),
+      note: "",
+      projectId: null,
+    }));
+  }
+
+  throw new Error(
+    `provider "${cfg.provider}" has no bulk read implemented yet.\n` +
+      `Add one in providers.mjs — see the dispatch table in SKILL.md.`
+  );
+}
+
+/**
+ * Run a provider CLI, keeping its output off any shared stream.
+ * @param {string} bin Executable name.
+ * @param {string[]} args Arguments.
+ * @param {NodeJS.ProcessEnv} env Environment for the child.
+ * @returns {string} Captured stdout.
+ */
+function run(bin, args, env) {
+  return execFileSync(bin, args, {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/**
+ * Apply the exposure boundary and reject an ambiguous set.
+ *
+ * The provider's own scoping is the default allowlist. The optional controls
+ * may only *narrow* it — there is intentionally no way to widen access from
+ * config, because that boundary belongs to the provider grant.
+ *
+ * A duplicate exact-name key is fatal rather than last-wins. Silently choosing
+ * one would make which credential gets used depend on provider response order,
+ * which is neither stable nor visible at the call site.
+ * @param {Array<object>} rows Raw provider rows.
+ * @param {{projectIds: string[], excludeKeys: string[]}} narrow Narrowing controls.
+ * @returns {Map<string, {value: string, note: string, id: string|null}>} Selected secrets by name.
+ */
+export function normalizeRows(
+  rows,
+  narrow = { projectIds: [], excludeKeys: [] }
+) {
+  const projects = new Set(narrow.projectIds ?? []);
+  const excluded = new Set([...(narrow.excludeKeys ?? []), LEASE_KEY]);
+  const out = new Map();
+
+  for (const row of rows) {
+    if (projects.size && !projects.has(row.projectId)) continue;
+    if (typeof row.key !== "string" || !ENV_KEY.test(row.key)) continue;
+    if (excluded.has(row.key)) continue;
+    if (out.has(row.key)) {
+      throw new Error(
+        `duplicate secret key across visible projects: ${row.key}.\n` +
+          `Resolve it at the provider — choosing one here would make credential ` +
+          `use depend on response order.`
+      );
+    }
+    if (typeof row.value !== "string") {
+      throw new Error(`secret value is not a string: ${row.key}`);
+    }
+    out.set(row.key, {
+      value: row.value,
+      note: row.note ?? "",
+      id: row.id ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read and select in one step — the normal entry point for consumers.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Map<string, {value: string, note: string, id: string|null}>} Selected secrets.
+ */
+export function fetchAll(cfg) {
+  return normalizeRows(fetchRaw(cfg), cfg.narrow);
+}
+
+/**
+ * Find one raw row by exact key, bypassing the exposure boundary.
+ *
+ * Only the rotation path uses this, and only to reach the lease record, which
+ * is deliberately excluded from every normal selection. Reading a *credential*
+ * must always go through {@link fetchAll} so the boundary applies.
+ * @param {object} cfg Resolved configuration.
+ * @param {string} key Exact key name.
+ * @returns {object|null} The raw row, or null when absent.
+ */
+export function rawByKey(cfg, key) {
+  const matches = fetchRaw(cfg).filter(row => row.key === key);
+  if (matches.length > 1) throw new Error(`duplicate secret key: ${key}`);
+  return matches[0] ?? null;
+}
+
+/**
+ * Write a replacement value back to the provider.
+ *
+ * Passing a value as an argument is normally forbidden, because process
+ * arguments are visible to anyone who can run `ps` on the same host. The
+ * Bitwarden CLI exposes no stdin path for an edit, so this is a documented
+ * exception rather than an oversight: it is confined to the one operation that
+ * cannot be expressed otherwise, and `execFileSync` at least keeps the value
+ * out of a shell and therefore out of shell history.
+ * @param {object} cfg Resolved configuration.
+ * @param {string} id Provider-side identifier for the secret.
+ * @param {string} value Replacement value.
+ */
+export function writeSecret(cfg, id, value) {
+  const env = { ...process.env };
+  const token = bootstrapToken(cfg.bootstrap);
+  if (cfg.bootstrap.key && token) env[cfg.bootstrap.key] = token;
+
+  if (cfg.provider === "bitwarden") {
+    run("bws", ["secret", "edit", id, "--value", value], env);
+    return;
+  }
+  throw new Error(
+    `provider "${cfg.provider}" has no write implemented.\n` +
+      `Rotation requires a proven write path; add one in providers.mjs.`
+  );
+}