@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/lisa-cursor/skills/lisa-secrets-access/scripts/read-secret-note.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Print one credential's usage note without opening the values file.
+ *
+ * This is a separate program from the resolver on purpose. An agent about to
+ * use a credential needs to know its blast radius — scope, owner, rotation,
+ * cautions — and should be able to learn that without any code path that could
+ * serialize a secret value. Values never enter this process, so its output
+ * cannot leak one even if it is logged.
+ *
+ * Usage:
+ *   read-secret-note.mjs NAME
+ * @module read-secret-note
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { materializedPaths, readConfig } from "./surfaces.mjs";
+
+/** A key must be an exact environment-variable name; see the naming rule. */
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Load the notes manifest, rejecting a shape this version does not understand.
+ * @param {string} notesFile Path to `secret-notes.json`.
+ * @returns {Record<string, string>} Notes by exact key name.
+ */
+export function loadNotes(notesFile) {
+  if (!existsSync(notesFile)) {
+    throw new Error(
+      `secret notes are unavailable at ${notesFile}.\n` +
+        `Run the remote environment bootstrap before using a credential.`
+    );
+  }
+  const payload = JSON.parse(readFileSync(notesFile, "utf8"));
+  if (payload.schemaVersion !== 1 || typeof payload.secrets !== "object") {
+    throw new Error("unsupported or malformed secret-notes manifest");
+  }
+  return payload.secrets;
+}
+
+/**
+ * Resolve one note, treating absence as a stop condition rather than a default.
+ *
+ * A missing note is deliberately fatal for the credential that lacks it. The
+ * alternative — carrying on with an inferred purpose — is how a token scoped to
+ * one repository gets used against another, and the failure is silent.
+ * @param {string} name Exact environment-variable name.
+ * @param {Record<string, string>} notes Loaded manifest entries.
+ * @returns {string} The note text.
+ */
+export function noteFor(name, notes) {
+  if (!ENV_KEY.test(name)) {
+    throw new Error("secret key must be an exact environment-variable name");
+  }
+  const note = notes[name];
+  if (typeof note !== "string" || !note.trim()) {
+    throw new Error(
+      `no usable note exists for ${name}.\n` +
+        `A missing or ambiguous note is a stop condition for that credential — ` +
+        `do not infer its purpose from its name.`
+    );
+  }
+  return note;
+}
+
+function main() {
+  const [name] = process.argv.slice(2);
+  if (!name) throw new Error("usage: read-secret-note.mjs NAME");
+  const cfg = readConfig();
+  const { notesFile } = materializedPaths(cfg.namespace);
+  console.log(noteFor(name, loadNotes(notesFile)));
+}
+
+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/resolve-secret.mjs

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 /**
- * Resolve a secret through the configured provider.
+ * Resolve a secret through the configured provider and surface.
  *
  * The executable half of `lisa-secrets-access`. It exists as a CLI rather than
  * a library because the callers are polyglot — Python scripts, shell, and
  * TypeScript all need the same answer, and a subprocess is the only interface
  * all three share without duplicating the logic three times.
  *
- * Resolution order is environment, then provider. The environment comes first
- * so a CI run — where secrets are injected by the pipeline — never reaches for
- * a provider or a local store at all.
+ * The resolution ladder is one rule with one order:
+ *
+ *   environment  ->  materialized file (surfaces that have one)  ->  provider
+ *
+ * Environment comes first so a CI run, where the pipeline injects secrets,
+ * never reaches for a provider or a local store at all. The middle rung exists
+ * only on surfaces whose bootstrap runs before the consuming process does.
  *
  * Values are written to stdout with no trailing newline and nothing else, so
  * `$(resolve-secret.mjs get NAME)` is safe. Diagnostics go to stderr.
@@ -19,160 +23,65 @@
  *   resolve-secret.mjs list
  *   resolve-secret.mjs describe NAME
  *   resolve-secret.mjs verify
+ *   resolve-secret.mjs surface
+ * @module resolve-secret
  */
 
-import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 
-/** Config defaults when `.lisa.config.json` carries no `secrets` block. */
-const DEFAULTS = {
-  provider: "env",
-  bootstrap: { sources: ["env"], key: null },
-  require: null,
-};
+import { parseEnv } from "./envfile.mjs";
+import { ENV_KEY, fetchAll } from "./providers.mjs";
+import { materializedPaths, readConfig } from "./surfaces.mjs";
 
-/**
- * Read the `secrets` block from `.lisa.config.json`.
- * @param {string} cwd Directory to look in.
- * @returns {{provider: string, bootstrap: {sources: string[], key: string|null}, require: string[]|null}}
- */
-export function readConfig(cwd = process.cwd()) {
-  const path = join(cwd, ".lisa.config.json");
-  if (!existsSync(path)) return DEFAULTS;
-  try {
-    const cfg = JSON.parse(readFileSync(path, "utf8")).secrets;
-    if (!cfg) return DEFAULTS;
-    return {
-      provider: cfg.provider ?? DEFAULTS.provider,
-      bootstrap: { ...DEFAULTS.bootstrap, ...(cfg.bootstrap ?? {}) },
-      require: cfg.require ?? null,
-    };
-  } catch (err) {
-    throw new Error(`.lisa.config.json is not readable: ${err.message}`);
-  }
-}
+export { readConfig };
 
 /**
- * Obtain the one credential that unlocks the provider.
+ * Read the materialized values file, if this surface has one.
  *
- * Walks `sources` in order. This is the only credential permitted in an OS
- * keychain — it is a bootstrap, not a cached copy of anything.
- * @param {{sources: string[], key: string|null}} bootstrap Bootstrap config.
- * @returns {string|null} The token, or null when the provider needs none.
+ * A surface without the capability returns empty rather than throwing: the
+ * absence of a middle rung is normal, not an error.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Map<string, string>} Values by exact name.
  */
-function bootstrapToken(bootstrap) {
-  if (!bootstrap.key) return null;
-  for (const source of bootstrap.sources) {
-    if (source === "env") {
-      const v = (process.env[bootstrap.key] ?? "").trim();
-      if (v) return v;
-    }
-    if (source === "keychain" && process.platform === "darwin") {
-      try {
-        const v = execFileSync(
-          "security",
-          [
-            "find-generic-password",
-            "-s",
-            bootstrap.key,
-            "-a",
-            process.env.USER ?? "",
-            "-w",
-          ],
-          { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
-        ).trim();
-        if (v) return v;
-      } catch {
-        /* not present in the keychain; try the next source */
-      }
-    }
-  }
-  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.`
-  );
+export function readMaterialized(cfg) {
+  if (!cfg.capabilities.materialized) return new Map();
+  const { valuesFile } = materializedPaths(cfg.namespace);
+  if (!existsSync(valuesFile)) return new Map();
+  return parseEnv(readFileSync(valuesFile, "utf8"));
 }
 
 /**
- * Fetch every secret the provider grants, keyed by name.
+ * Assert a name is declared when the project narrows itself with `require`.
  *
- * Deliberately fetches all rather than one: the provider already scopes what
- * this caller may see, so the set it returns *is* the permitted set, and
- * re-stating that as a list in config would duplicate a boundary the provider
- * already enforces.
- * @param {ReturnType<typeof readConfig>} cfg Resolved config.
- * @returns {Map<string, {value: string, note: string}>} Secrets by name.
+ * A `require` list is an assertion, not merely a filter: naming a secret
+ * declares the project needs it, so asking for one outside the list is a
+ * configuration error rather than a lookup miss.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
  */
-function fetchAll(cfg) {
-  const out = new Map();
-  const token = bootstrapToken(cfg.bootstrap);
-  const env = { ...process.env };
-  if (cfg.bootstrap.key && token) env[cfg.bootstrap.key] = token;
-
-  switch (cfg.provider) {
-    case "env":
-      for (const [k, v] of Object.entries(process.env)) {
-        if (/^[A-Z][A-Z0-9_]*$/.test(k))
-          out.set(k, { value: v ?? "", note: "" });
-      }
-      return out;
-
-    case "bitwarden": {
-      const raw = execFileSync("bws", ["secret", "list", "--output", "json"], {
-        encoding: "utf8",
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      for (const s of JSON.parse(raw || "[]")) {
-        out.set(s.key, { value: s.value, note: s.note ?? "" });
-      }
-      return out;
-    }
-
-    case "doppler": {
-      const raw = execFileSync(
-        "doppler",
-        ["secrets", "download", "--no-file", "--format", "json"],
-        {
-          encoding: "utf8",
-          env,
-          stdio: ["ignore", "pipe", "pipe"],
-        }
-      );
-      for (const [k, v] of Object.entries(JSON.parse(raw || "{}"))) {
-        out.set(k, { value: String(v), note: "" });
-      }
-      return out;
-    }
-
-    default:
-      throw new Error(
-        `provider "${cfg.provider}" has no bulk read implemented yet.\n` +
-          `Add one in resolve-secret.mjs — see the dispatch table in SKILL.md.`
-      );
+function assertDeclared(name, cfg) {
+  if (cfg.require && !cfg.require.includes(name)) {
+    throw new Error(
+      `${name} is not declared in secrets.require.\n` +
+        `Declared: ${cfg.require.join(", ") || "(none)"}`
+    );
   }
 }
 
 /**
- * Resolve one secret: environment first, then the provider.
+ * Resolve one secret down the ladder.
  * @param {string} name Environment-variable-style key.
- * @param {ReturnType<typeof readConfig>} [cfg] Resolved config.
+ * @param {object} [cfg] Resolved configuration.
  * @returns {string} The secret value.
  */
 export function get(name, cfg = readConfig()) {
   const fromEnv = (process.env[name] ?? "").trim();
   if (fromEnv) return fromEnv;
 
-  // A `require` list is an assertion, not just a filter: naming a secret
-  // declares that this project needs it, so asking for one outside the list is
-  // a configuration error rather than a lookup miss.
-  if (cfg.require && !cfg.require.includes(name)) {
-    throw new Error(
-      `${name} is not declared in secrets.require.\n` +
-        `Declared: ${cfg.require.join(", ") || "(none)"}`
-    );
-  }
+  assertDeclared(name, cfg);
+
+  const fromFile = readMaterialized(cfg).get(name);
+  if (fromFile) return fromFile;
 
   const all = fetchAll(cfg);
   const hit = all.get(name);
@@ -186,10 +95,108 @@ export function get(name, cfg = readConfig()) {
   return hit.value;
 }
 
+/**
+ * Report which rung of the ladder answers for a name, without revealing values.
+ * @param {string} name Requested name.
+ * @param {Map<string, object>} provider Provider view.
+ * @param {Map<string, string>} file Materialized view.
+ * @returns {string} A fixed-width source label.
+ */
+function sourceOf(name, provider, file) {
+  if ((process.env[name] ?? "").trim()) return "env      ";
+  if (file.get(name)) return "file     ";
+  if (provider.get(name)?.value) return "provider ";
+  return "         ";
+}
+
+/**
+ * Verify every declared secret, mirroring the ladder's own order.
+ *
+ * Checking only the provider would report MISSING for every secret in CI, where
+ * the pipeline injects them as environment variables — a false negative exactly
+ * where verification matters most.
+ *
+ * This command is read-only. Proving that a rotating credential can actually be
+ * written back requires a write, so that check lives in the rotation path
+ * rather than here.
+ * @param {object} cfg Resolved configuration.
+ * @returns {number} Count of secrets that failed.
+ */
+function verify(cfg) {
+  const provider = fetchAll(cfg);
+  const file = readMaterialized(cfg);
+  const names = cfg.require ?? [
+    ...new Set([...provider.keys(), ...file.keys()]),
+  ];
+  const rotating = new Set(cfg.rotating ?? []);
+  let bad = 0;
+
+  console.log(`surface: ${cfg.surface}   provider: ${cfg.provider}`);
+  for (const name of names) {
+    const resolves = Boolean(
+      (process.env[name] ?? "").trim() ||
+      file.get(name) ||
+      provider.get(name)?.value
+    );
+    const named = ENV_KEY.test(name);
+    const noted = Boolean(provider.get(name)?.note);
+    if (!resolves || !named || !noted) bad += 1;
+    console.log(
+      `  ${name.padEnd(30)} ${resolves ? "resolves" : "MISSING "} ` +
+        `${sourceOf(name, provider, file)} ` +
+        `${named ? "name ok" : "NAME NOT UPPER_SNAKE"}  ` +
+        `${noted ? "noted" : "NO NOTE"}` +
+        `${rotating.has(name) ? "  rotating" : ""}`
+    );
+  }
+
+  for (const name of rotating) {
+    if (!cfg.bootstrap.key) {
+      console.log(
+        `  ${name.padEnd(30)} ROTATING BUT NO BOOTSTRAP — the replacement could ` +
+          `not be written back, which strands the credential on first use`
+      );
+      bad += 1;
+    }
+  }
+  return bad;
+}
+
+/**
+ * Describe a secret's usage note without ever printing its value.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ */
+function describe(name, cfg) {
+  const hit = fetchAll(cfg).get(name);
+  if (hit) {
+    // Infer *and* warn, never instead of. A silent fallback that works well
+    // enough is what guarantees the notes stay empty forever.
+    console.log(
+      hit.note ||
+        `(no note — purpose inferred from the name: ${name}. ` +
+          `An inferred mapping must never authorise a write.)`
+    );
+    return;
+  }
+  // Environment-only is a legitimate state, not an error: CI injects secrets
+  // that never appear in a provider listing. Say so rather than claiming the
+  // secret does not exist, and never print the value.
+  if ((process.env[name] ?? "").trim()) {
+    console.log("(set in the environment; no provider entry, so no note)");
+    return;
+  }
+  throw new Error(`${name} not found in the environment or the provider`);
+}
+
 function main() {
   const [op, name] = process.argv.slice(2);
   const cfg = readConfig();
 
+  if (op === "surface") {
+    console.log(cfg.surface);
+    return;
+  }
   if (op === "get") {
     if (!name) throw new Error("usage: resolve-secret.mjs get NAME");
     process.stdout.write(get(name, cfg));
@@ -197,58 +204,26 @@ function main() {
   }
   if (op === "list") {
     // Names only. This command must never be able to leak a value.
-    console.log([...fetchAll(cfg).keys()].sort().join("\n"));
+    const names = new Set([
+      ...fetchAll(cfg).keys(),
+      ...readMaterialized(cfg).keys(),
+    ]);
+    console.log([...names].sort().join("\n"));
     return;
   }
   if (op === "describe") {
     if (!name) throw new Error("usage: resolve-secret.mjs describe NAME");
-    const hit = fetchAll(cfg).get(name);
-    if (hit) {
-      console.log(
-        hit.note || `(no note — purpose inferred from the name: ${name})`
-      );
-      return;
-    }
-    // Environment-only is a legitimate state, not an error: CI injects secrets
-    // that never appear in the provider listing. Say so rather than claiming
-    // the secret does not exist, and never print the value.
-    if ((process.env[name] ?? "").trim()) {
-      console.log(
-        `(set in the environment; no provider entry, so no note is available)`
-      );
-      return;
-    }
-    throw new Error(`${name} not found in the environment or the provider`);
+    describe(name, cfg);
+    return;
   }
   if (op === "verify") {
-    const all = fetchAll(cfg);
-    const names = cfg.require ?? [...all.keys()];
-    let bad = 0;
-    for (const n of names) {
-      // Mirror get()'s environment-first order. Checking only the provider
-      // reports MISSING for every secret in CI, where the pipeline injects
-      // them as environment variables — a false negative precisely where
-      // verification matters most.
-      const fromEnv = Boolean((process.env[n] ?? "").trim());
-      const entry = all.get(n);
-      const ok = fromEnv || Boolean(entry?.value);
-      const named = /^[A-Z][A-Z0-9_]*$/.test(n);
-      const noted = Boolean(entry?.note);
-      if (!ok || !named) bad += 1;
-      const source = fromEnv
-        ? "env     "
-        : entry?.value
-          ? "provider"
-          : "        ";
-      console.log(
-        `  ${n.padEnd(30)} ${ok ? "resolves" : "MISSING "} ${source}  ` +
-          `${named ? "name ok" : "NAME NOT UPPER_SNAKE"}  ${noted ? "noted" : "no note"}`
-      );
-    }
+    const bad = verify(cfg);
     if (bad) throw new Error(`${bad} secret(s) failed verification`);
     return;
   }
-  throw new Error("usage: resolve-secret.mjs get|list|describe|verify [NAME]");
+  throw new Error(
+    "usage: resolve-secret.mjs get|list|describe|verify|surface [NAME]"
+  );
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {