@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/lisa-cursor/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);
+  }
+}

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Surface definitions and configuration for `lisa-secrets-access`.
+ *
+ * A *provider* is where secrets live. A *surface* is where the running code
+ * lives, and it determines how secrets reach that code. These are independent
+ * axes: the same Bitwarden project serves a laptop, a CI runner, and a remote
+ * agent container, but each of the three obtains its values differently.
+ *
+ * Surfaces are declared by capability rather than by name so adding one is a
+ * single entry here rather than a new branch in every consumer. That is the
+ * whole reason this table exists.
+ * @module surfaces
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Capabilities, per surface.
+ *
+ * `materialized` — the surface obtains values from files written before the
+ * code ran, so the resolver must consult them.
+ *
+ * `mayWriteValues` — the surface is permitted to write resolved values to
+ * disk. This is normally forbidden, because a value on disk is a copy that can
+ * drift and leak. It is *required* on surfaces whose bootstrap runs before the
+ * consuming process exists and which therefore have no other channel; a remote
+ * agent container prepares itself during setup, long before any task starts.
+ */
+export const SURFACES = {
+  local: { materialized: false, mayWriteValues: false },
+  "github-actions": { materialized: false, mayWriteValues: false },
+  "codex-cloud": { materialized: true, mayWriteValues: true },
+};
+
+/** Config defaults when `.lisa.config.json` carries no `secrets` block. */
+const DEFAULTS = {
+  provider: "env",
+  bootstrap: { sources: ["env"], key: null },
+  require: null,
+  rotating: [],
+  namespace: "lisa",
+  narrow: { projectIds: [], excludeKeys: [] },
+  surface: null,
+};
+
+/**
+ * Identify the surface this process is running on.
+ *
+ * An explicit value always wins, so an operator can reproduce another
+ * surface's behaviour locally when diagnosing one. Detection is otherwise
+ * ordered most-specific first.
+ * @param {string|null} [configured] Surface named in `.lisa.config.json`.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @returns {string} A key of {@link SURFACES}.
+ */
+export function detectSurface(configured = null, env = process.env) {
+  const explicit = (env.LISA_SECRETS_SURFACE ?? "").trim() || configured;
+  if (explicit) {
+    if (!SURFACES[explicit]) {
+      throw new Error(
+        `unknown surface "${explicit}".\n` +
+          `Known: ${Object.keys(SURFACES).join(", ")}`
+      );
+    }
+    return explicit;
+  }
+  if ((env.GITHUB_ACTIONS ?? "") === "true") return "github-actions";
+  if ((env.CODEX_SANDBOX ?? env.CODEX_HOME ?? "") !== "") return "codex-cloud";
+  return "local";
+}
+
+/**
+ * Reject a namespace that is not exactly one safe path segment.
+ *
+ * The namespace is joined onto a config root, so anything containing a
+ * separator or a parent reference could redirect writes outside the intended
+ * directory. Validating here means every caller inherits the guard.
+ * @param {string} namespace Candidate namespace.
+ * @returns {string} The namespace, unchanged, when valid.
+ */
+export function assertNamespace(namespace) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(namespace) || namespace === "..") {
+    throw new Error(
+      `secrets.namespace must be one safe path segment, got "${namespace}"`
+    );
+  }
+  return namespace;
+}
+
+/**
+ * Where a surface's materialized files live.
+ * @param {string} namespace Validated namespace.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @returns {{dir: string, valuesFile: string, notesFile: string}} Paths.
+ */
+export function materializedPaths(namespace, env = process.env) {
+  const root = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+  const dir = join(root, assertNamespace(namespace));
+  return {
+    dir,
+    valuesFile: join(dir, "secrets.env"),
+    notesFile: join(dir, "secret-notes.json"),
+  };
+}
+
+/**
+ * Read the `secrets` block from `.lisa.config.json`.
+ *
+ * A project with no block is a supported state, not an error: the `env`
+ * provider means the environment *is* the provider. A credentials manager is
+ * the preferred path, never a required one.
+ * @param {string} [cwd] Directory to look in.
+ * @returns {object} Resolved configuration with defaults applied.
+ */
+export function readConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return withSurface(DEFAULTS);
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8")).secrets;
+  } catch (err) {
+    throw new Error(`.lisa.config.json is not readable: ${err.message}`);
+  }
+  if (!cfg) return withSurface(DEFAULTS);
+  return withSurface({
+    provider: cfg.provider ?? DEFAULTS.provider,
+    bootstrap: { ...DEFAULTS.bootstrap, ...(cfg.bootstrap ?? {}) },
+    require: cfg.require ?? null,
+    rotating: cfg.rotating ?? [],
+    namespace: assertNamespace(cfg.namespace ?? DEFAULTS.namespace),
+    narrow: { ...DEFAULTS.narrow, ...(cfg.narrow ?? {}) },
+    surface: cfg.surface ?? null,
+  });
+}
+
+/**
+ * Attach the resolved surface and its capabilities to a configuration.
+ * @param {object} cfg Configuration without surface resolution.
+ * @returns {object} The same configuration plus `surface` and `capabilities`.
+ */
+function withSurface(cfg) {
+  const surface = detectSurface(cfg.surface);
+  return { ...cfg, surface, capabilities: SURFACES[surface] };
+}

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Validate the `secrets`, `remoteEnv`, and `automations` blocks.
+ *
+ * These blocks are read by shell, by Node, and by generated workflows, so a
+ * malformed one surfaces late and somewhere unhelpful — a container that fails
+ * mid-setup, a scheduled loop that never fires, a dispatch that names a surface
+ * nobody provisioned. Checking the shape up front turns all of those into one
+ * message at `doctor` time.
+ *
+ * Structure only. Whether a credential resolves is `doctor-secrets.mjs`; this
+ * asks whether the declaration could ever be correct.
+ *
+ * Usage:
+ *   validate-config.mjs
+ * @module validate-config
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Providers with a read implementation today. */
+const IMPLEMENTED_PROVIDERS = new Set(["bitwarden", "doppler", "env"]);
+
+/** Providers named in the dispatch table but not yet implemented. */
+const DECLARED_PROVIDERS = new Set(["1password", "aws", "vault"]);
+
+/** Surfaces the resolver knows. */
+const SURFACES = new Set(["local", "github-actions", "codex-cloud"]);
+
+/** Install methods the toolchain runner supports. */
+const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
+
+/**
+ * Validate the `secrets` block.
+ * @param {object|undefined} secrets The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateSecrets(secrets) {
+  if (!secrets) return [];
+  const problems = [];
+  const provider = secrets.provider ?? "env";
+
+  if (DECLARED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is documented but has no read ` +
+        `implementation yet. Add one in providers.mjs rather than configuring it.`
+    );
+  } else if (!IMPLEMENTED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is unknown. ` +
+        `Known: ${[...IMPLEMENTED_PROVIDERS, ...DECLARED_PROVIDERS].join(", ")}.`
+    );
+  }
+
+  if (
+    secrets.namespace &&
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(secrets.namespace)
+  ) {
+    problems.push(
+      `secrets.namespace "${secrets.namespace}" is not one safe path segment. ` +
+        `It is joined onto a config root, so a separator could redirect writes.`
+    );
+  }
+
+  if (secrets.surface && !SURFACES.has(secrets.surface)) {
+    problems.push(
+      `secrets.surface "${secrets.surface}" is unknown. ` +
+        `Known: ${[...SURFACES].join(", ")}.`
+    );
+  }
+
+  for (const field of ["require", "rotating"]) {
+    const value = secrets[field];
+    if (value === undefined || value === null) continue;
+    if (!Array.isArray(value)) {
+      problems.push(`secrets.${field} must be an array of exact key names`);
+      continue;
+    }
+    for (const name of value) {
+      if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+        problems.push(
+          `secrets.${field} entry ${JSON.stringify(name)} is not an exact ` +
+            `UPPER_SNAKE_CASE environment-variable name. Lookup is never fuzzy.`
+        );
+      }
+    }
+  }
+
+  if ((secrets.rotating ?? []).length && !secrets.bootstrap?.key) {
+    problems.push(
+      `secrets.rotating is declared but secrets.bootstrap.key is not. A ` +
+        `rotating credential whose replacement cannot be written back is ` +
+        `stranded the first time it is used.`
+    );
+  }
+
+  return problems;
+}
+
+/**
+ * Validate the `remoteEnv` block.
+ * @param {object|undefined} remoteEnv The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateRemoteEnv(remoteEnv) {
+  if (!remoteEnv) return [];
+  const problems = [];
+
+  for (const tool of remoteEnv.tools?.require ?? []) {
+    if (!tool.name) problems.push("remoteEnv.tools.require entry has no name");
+  }
+  for (const tool of remoteEnv.tools?.install ?? []) {
+    if (!tool.name) {
+      problems.push("remoteEnv.tools.install entry has no name");
+      continue;
+    }
+    if (!tool.version) {
+      problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
+    }
+    if (!INSTALL_METHODS.has(tool.install)) {
+      problems.push(
+        `remoteEnv install "${tool.name}" has method ${JSON.stringify(tool.install)}. ` +
+          `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+      );
+      continue;
+    }
+    if (tool.install === "release-zip" && !(tool.url && tool.sha256)) {
+      problems.push(
+        `remoteEnv install "${tool.name}" needs both url and sha256. A pinned ` +
+          `version with no checksum still trusts whatever the URL serves today.`
+      );
+    }
+    if (tool.install === "npm-global" && !tool.package) {
+      problems.push(`remoteEnv install "${tool.name}" needs a package`);
+    }
+  }
+
+  for (const [surface, block] of Object.entries(remoteEnv.surfaces ?? {})) {
+    if (!SURFACES.has(surface)) {
+      problems.push(`remoteEnv.surfaces has unknown surface "${surface}"`);
+    }
+    if (!block.repository) {
+      problems.push(`remoteEnv.surfaces["${surface}"] has no repository`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Validate the `automations` block against declared surfaces.
+ * @param {object|undefined} automations The block, if present.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @returns {string[]} Problems found.
+ */
+export function validateAutomations(automations, remoteEnv) {
+  if (!automations) return [];
+  const problems = [];
+
+  for (const [name, loop] of Object.entries(automations)) {
+    if (loop.scheduler !== "github-actions") continue;
+    if (!loop.schedule) {
+      problems.push(`automations["${name}"] has no schedule`);
+    }
+    if (!loop.executionEnv) {
+      problems.push(`automations["${name}"] has no executionEnv`);
+      continue;
+    }
+    if (!SURFACES.has(loop.executionEnv)) {
+      problems.push(
+        `automations["${name}"].executionEnv "${loop.executionEnv}" is unknown`
+      );
+      continue;
+    }
+    if (!remoteEnv?.surfaces?.[loop.executionEnv]?.repository) {
+      problems.push(
+        `automations["${name}"] dispatches to "${loop.executionEnv}", which is ` +
+          `not provisioned. Run /lisa:setup:remote-env ${loop.executionEnv} first.`
+      );
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Validate every block this plan introduced.
+ * @param {object} cfg Parsed `.lisa.config.json`.
+ * @returns {string[]} Problems found.
+ */
+export function validateConfig(cfg) {
+  return [
+    ...validateSecrets(cfg.secrets),
+    ...validateRemoteEnv(cfg.remoteEnv),
+    ...validateAutomations(cfg.automations, cfg.remoteEnv),
+  ];
+}
+
+function main() {
+  const path = join(process.cwd(), ".lisa.config.json");
+  if (!existsSync(path)) {
+    console.log("no .lisa.config.json — nothing to validate");
+    return;
+  }
+  const problems = validateConfig(JSON.parse(readFileSync(path, "utf8")));
+  if (!problems.length) {
+    console.log(
+      "config: secrets, remoteEnv and automations blocks are well-formed"
+    );
+    return;
+  }
+  for (const problem of problems) console.error(`  ${problem}`);
+  throw new Error(`${problems.length} configuration problem(s)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}