@codyswann/lisa 2.316.2 → 2.317.1

package/plugins/lisa/.codex-plugin/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]}`) {

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/rotate-secret.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * The single-writer path for consumable credentials.
+ *
+ * A *consumable* credential is one where using it can invalidate the stored
+ * copy: an OAuth refresh token the issuer replaces on every exchange, a
+ * short-lived session, a single-use enrollment token. The property is not
+ * "OAuth" — it is that a successful use makes the value on record wrong.
+ *
+ * This is a deliberate sibling of the resolver rather than a mode of it. The
+ * resolver never writes, and that is what makes it safe to hand to anything. A
+ * credential that must be written back needs an authority the read path should
+ * not hold, so it gets its own program and its own contract.
+ *
+ * The failure this exists to prevent is not rotation. It is **rotation with no
+ * proven write path**: a job exchanges the token, the issuer invalidates the
+ * old one, the replacement cannot be saved, and every downstream consumer is
+ * broken until a human notices. So the write is proven *before* the
+ * irreversible use, never after.
+ *
+ * Usage:
+ *   rotate-secret.mjs preflight NAME     # prove the write path, change nothing
+ *   rotate-secret.mjs checkout NAME      # preflight, take the lease, emit value
+ *   rotate-secret.mjs commit NAME        # read replacement on stdin, release
+ *   rotate-secret.mjs release NAME       # release without writing
+ *   rotate-secret.mjs leases             # show current holders
+ * @module rotate-secret
+ */
+
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+
+import { LEASE_KEY, fetchAll, rawByKey, writeSecret } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+
+/** How long a lease is honoured before it is treated as abandoned. */
+const LEASE_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Assert a name is declared rotating before any write path opens for it.
+ *
+ * Declaration is config, never inference from a note: the note lives
+ * provider-side, is editable outside review, and a read-only account cannot
+ * correct a wrong one. Config is the surface where this decision is reviewable.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ */
+function assertRotating(name, cfg) {
+  if (!(cfg.rotating ?? []).includes(name)) {
+    throw new Error(
+      `${name} is not declared in secrets.rotating.\n` +
+        `Only a declared consumable credential may use the write path. If this ` +
+        `credential really is replaced on use, declare it — silently rotating an ` +
+        `undeclared one is how a shared token gets stranded.`
+    );
+  }
+}
+
+/**
+ * Locate a secret and its provider-side identifier.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ * @returns {{value: string, id: string}} The current entry.
+ */
+function entryFor(name, cfg) {
+  const hit = fetchAll(cfg).get(name);
+  if (!hit) throw new Error(`${name} is not available to this account`);
+  if (!hit.id) {
+    throw new Error(
+      `${name} has no provider identifier, so it cannot be written back.\n` +
+        `Provider "${cfg.provider}" may not support rotation.`
+    );
+  }
+  return { value: hit.value, id: hit.id };
+}
+
+/**
+ * Prove the replacement could be saved, by writing the value already stored.
+ *
+ * A no-op re-write is the only honest proof: it exercises the exact permission
+ * the rotation will need, against the exact record, and changes nothing. A
+ * check that merely confirms the CLI exists proves a different thing than the
+ * one that fails — which is precisely how the original incident happened.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ * @returns {{value: string, id: string}} The verified entry.
+ */
+export function preflight(name, cfg) {
+  assertRotating(name, cfg);
+  const entry = entryFor(name, cfg);
+  try {
+    writeSecret(cfg, entry.id, entry.value);
+  } catch (err) {
+    throw new Error(
+      `no write access to ${name}: ${String(err.message).split("\n")[0]}\n` +
+        `Refusing to continue. Rotating a credential whose replacement cannot ` +
+        `be persisted breaks every consumer of it.`
+    );
+  }
+  return entry;
+}
+
+/**
+ * Read the lease record, tolerating its absence.
+ * @param {object} cfg Resolved configuration.
+ * @returns {{row: object|null, leases: Record<string, object>}} Current state.
+ */
+function readLeases(cfg) {
+  const row = rawByKey(cfg, LEASE_KEY);
+  if (!row) return { row: null, leases: {} };
+  try {
+    const parsed = JSON.parse(row.value || "{}");
+    return { row, leases: typeof parsed === "object" ? parsed : {} };
+  } catch {
+    return { row, leases: {} };
+  }
+}
+
+/**
+ * Persist the lease record.
+ *
+ * When the record does not exist the lease is skipped rather than invented.
+ * Creating provider entries is not this program's authority, and an advisory
+ * lock whose absence blocks a legitimate rotation would be worse than no lock.
+ * @param {object} cfg Resolved configuration.
+ * @param {object|null} row Existing lease row.
+ * @param {Record<string, object>} leases Updated lease map.
+ */
+function writeLeases(cfg, row, leases) {
+  if (!row?.id) return;
+  writeSecret(cfg, row.id, JSON.stringify(leases));
+}
+
+/**
+ * Identify this holder well enough for a human to find it.
+ * @param {object} cfg Resolved configuration.
+ * @returns {string} A holder label.
+ */
+function holderId(cfg) {
+  const run = process.env.GITHUB_RUN_ID;
+  return run ? `${cfg.surface}:run-${run}` : `${cfg.surface}:${hostname()}`;
+}
+
+/**
+ * Take the advisory lease, refusing while another holder's lease is live.
+ *
+ * Advisory is the honest word. True cross-surface exclusion is not achievable
+ * with per-surface primitives, and claiming otherwise would invite exactly the
+ * concurrent rotation this guards against. What this does give is a record every
+ * surface can see, and an expiry so a crashed holder heals itself.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ * @param {number} now Current epoch milliseconds.
+ */
+function acquire(name, cfg, now) {
+  const { row, leases } = readLeases(cfg);
+  const held = leases[name];
+  const holder = holderId(cfg);
+  if (held && held.holder !== holder && Number(held.expiresAt) > now) {
+    throw new Error(
+      `${name} is leased by ${held.holder} until ` +
+        `${new Date(Number(held.expiresAt)).toISOString()}.\n` +
+        `Two refresh loops race: each receives a new value and invalidates the ` +
+        `other, and whichever wrote last wins while the other copy is dead.`
+    );
+  }
+  leases[name] = {
+    holder,
+    surface: cfg.surface,
+    acquiredAt: now,
+    expiresAt: now + LEASE_TTL_MS,
+  };
+  writeLeases(cfg, row, leases);
+}
+
+/**
+ * Release the lease if this holder owns it.
+ * @param {string} name Requested name.
+ * @param {object} cfg Resolved configuration.
+ */
+function release(name, cfg) {
+  const { row, leases } = readLeases(cfg);
+  if (leases[name]?.holder === holderId(cfg)) {
+    delete leases[name];
+    writeLeases(cfg, row, leases);
+  }
+}
+
+/**
+ * Read the replacement value from stdin.
+ *
+ * Stdin rather than an argument, because process arguments are visible to
+ * anything that can list processes on the host.
+ * @returns {string} The replacement value.
+ */
+function readStdin() {
+  const value = readFileSync(0, "utf8");
+  if (!value.trim()) {
+    throw new Error(
+      "no replacement value on stdin; refusing to store an empty secret"
+    );
+  }
+  return value;
+}
+
+function main() {
+  const [op, name] = process.argv.slice(2);
+  const cfg = readConfig();
+  const now = Date.now();
+
+  if (op === "leases") {
+    const { leases } = readLeases(cfg);
+    const rows = Object.entries(leases);
+    if (!rows.length) {
+      console.log("no rotation leases held");
+      return;
+    }
+    for (const [key, lease] of rows) {
+      const state = Number(lease.expiresAt) > now ? "held" : "expired";
+      console.log(
+        `  ${key.padEnd(30)} ${state.padEnd(8)} ${lease.holder}  ` +
+          `until ${new Date(Number(lease.expiresAt)).toISOString()}`
+      );
+    }
+    return;
+  }
+
+  if (!name) throw new Error(`usage: rotate-secret.mjs ${op ?? "OP"} NAME`);
+
+  if (op === "preflight") {
+    preflight(name, cfg);
+    console.log(`${name}: write path proven; nothing was changed`);
+    return;
+  }
+  if (op === "checkout") {
+    const entry = preflight(name, cfg);
+    acquire(name, cfg, now);
+    process.stdout.write(entry.value);
+    return;
+  }
+  if (op === "commit") {
+    assertRotating(name, cfg);
+    const { id } = entryFor(name, cfg);
+    writeSecret(cfg, id, readStdin());
+    release(name, cfg);
+    console.log(`${name}: replacement stored and lease released`);
+    return;
+  }
+  if (op === "release") {
+    release(name, cfg);
+    console.log(`${name}: lease released`);
+    return;
+  }
+  throw new Error(
+    "usage: rotate-secret.mjs preflight|checkout|commit|release|leases [NAME]"
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}