@codyswann/lisa 4.74.9 → 4.75.0

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

@@ -0,0 +1,297 @@
+#!/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, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { hostname } from "node:os";
+
+import {
+  LEASE_KEY,
+  fetchRotatable,
+  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) {
+  // Rotation view, not the materialization view: a name may be excluded from
+  // every surface and still need its replacement persisted. assertRotating has
+  // already proved this name is declared in config.
+  const hit = fetchRotatable(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]"
+  );
+}
+
+/**
+ * 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/routing-floor.mjs

@@ -0,0 +1,153 @@
+/**
+ * Derive the credentials a project's vendor routing already implies.
+ *
+ * `.lisa.config.json` declares `tracker` and `source` — which tracker receives
+ * ticket writes, which system hosts PRDs. Those two lines already determine a
+ * set of credentials without which nothing works: `tracker: "github"` cannot
+ * write an issue without `GH_TOKEN`, `source: "notion"` cannot read a PRD
+ * without `NOTION_API_TOKEN`.
+ *
+ * Until now that mapping lived only in prose, in `config-resolution.md`'s
+ * invariants, with nothing connecting it to `secrets.require`. So the two could
+ * drift silently and adding a vendor never added its credential to the asserted
+ * set — the list was hand-maintained when most of it was deducible.
+ *
+ * This module is that deduction, as code. The floor is *unioned* into the
+ * required set at resolution time rather than checked against a hand-written
+ * list, because correctness should not depend on someone having remembered to
+ * type `GH_TOKEN` into a file. A project still declares its extras — an
+ * `ATTIO_API_KEY` no routing can imply — in `secrets.require`.
+ *
+ * Deliberately not exhaustive about *optional* integrations. A credential
+ * appears here only when the routing that implies it makes the project
+ * non-functional without it. Sonar, Sentry and PostHog are configured
+ * separately and a project runs fine with none of them, so they are extras a
+ * project declares, not a floor anything derives.
+ * @module routing-floor
+ */
+
+/**
+ * The credential each destination tracker cannot operate without.
+ *
+ * Confluence and JIRA share `ATLASSIAN_API_TOKEN` because they are one vendor
+ * behind one token — the same reason `lisa-atlassian-access` serves both.
+ */
+const TRACKER_CREDENTIALS = {
+  jira: ["ATLASSIAN_API_TOKEN"],
+  github: ["GH_TOKEN"],
+  linear: ["LINEAR_API_KEY"],
+};
+
+/** The credential each PRD source cannot be read without. */
+const SOURCE_CREDENTIALS = {
+  notion: ["NOTION_API_TOKEN"],
+  confluence: ["ATLASSIAN_API_TOKEN"],
+  jira: ["ATLASSIAN_API_TOKEN"],
+  github: ["GH_TOKEN"],
+  linear: ["LINEAR_API_KEY"],
+};
+
+/**
+ * The credentials a project's routing makes mandatory.
+ *
+ * An unknown or absent vendor contributes nothing rather than throwing. This
+ * function answers "what does routing imply", and a `tracker` Lisa does not
+ * recognise is a *routing* error that `config-resolution`'s dispatch already
+ * reports with a better message than a credential check could. Failing here
+ * too would report the same defect twice, in the wrong vocabulary, and would
+ * make a preflight the place a typo in `tracker` first surfaces.
+ * @param {{tracker?: string, source?: string}} [routing] Vendor routing.
+ * @returns {readonly string[]} Sorted, de-duplicated credential names.
+ */
+export function routingFloor(routing = {}) {
+  const tracker = normalize(routing.tracker);
+  const source = normalize(routing.source);
+  const names = [
+    ...credentialsFor(TRACKER_CREDENTIALS, tracker),
+    ...credentialsFor(SOURCE_CREDENTIALS, source),
+  ];
+  return [...new Set(names)].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Explain which routing key implied each credential.
+ *
+ * The preflight reports a missing credential to whoever has to fix it, and
+ * "GH_TOKEN is required" is a much weaker sentence than "GH_TOKEN is required
+ * because tracker is github". The second names the line of config to change if
+ * the requirement itself is wrong, which is the other valid remedy.
+ * @param {{tracker?: string, source?: string}} [routing] Vendor routing.
+ * @returns {Record<string, string[]>} Credential name to the reasons for it.
+ */
+export function routingFloorReasons(routing = {}) {
+  const tracker = normalize(routing.tracker);
+  const source = normalize(routing.source);
+  const reasons = {};
+  for (const name of credentialsFor(TRACKER_CREDENTIALS, tracker)) {
+    reasons[name] = [`tracker is "${tracker}"`];
+  }
+  for (const name of credentialsFor(SOURCE_CREDENTIALS, source)) {
+    reasons[name] = [...(reasons[name] ?? []), `source is "${source}"`];
+  }
+  return reasons;
+}
+
+/**
+ * Look a vendor up without consulting anything it inherited.
+ *
+ * A routing value reaches these maps as an arbitrary string from a config file,
+ * and plain indexing answers `constructor` and `__proto__` with inherited
+ * members rather than with undefined — so `?? []` never fires and spreading the
+ * result throws `not iterable`. `routingFloor` runs inside `readConfig`, which
+ * means a typo in `tracker` would abort configuration loading with an
+ * iterability error, in place of the documented behavior: an unrecognised
+ * vendor contributes nothing, and routing dispatch reports the typo in its own
+ * vocabulary.
+ * @param {Record<string, string[]>} map Credential map to read.
+ * @param {string} key Normalized vendor name.
+ * @returns {string[]} Declared credentials, empty for anything not declared.
+ */
+function credentialsFor(map, key) {
+  return Object.hasOwn(map, key) ? map[key] : [];
+}
+
+/**
+ * Substrates that satisfy a credential without the variable being set.
+ *
+ * A required name is a proxy for a capability, not an end in itself, and some
+ * capabilities have a second legitimate route. `gh` authenticates from its own
+ * keyring after `gh auth login`, so a laptop can drive every GitHub operation
+ * Lisa performs with `GH_TOKEN` unset — which is the normal state of a
+ * developer machine, not a misconfiguration.
+ *
+ * Without this the floor fails a local session over a credential that surface
+ * demonstrably does not need. That is worse than not checking: a control that
+ * fires when nothing is wrong is one people learn to skip, and it would have
+ * fired on every session in Lisa's own repository.
+ *
+ * This mirrors the credential-substrate-precedence contract the access skills
+ * already follow — a capability is proven by whichever substrate can serve it,
+ * not by one hardcoded variable.
+ *
+ * Kept deliberately small. An entry belongs here only when the alternative is
+ * genuinely equivalent for everything Lisa does with that credential and can be
+ * proven by a cheap local command. `ATLASSIAN_API_TOKEN` is not listed even
+ * though `acli` exists, because the contract ranks the token first and acli
+ * covers only part of the surface.
+ */
+export const SUBSTITUTE_SUBSTRATES = {
+  GH_TOKEN: {
+    command: "gh",
+    args: ["auth", "status"],
+    describes: "the gh CLI is authenticated (gh auth login)",
+  },
+};
+
+/**
+ * Lower-case a routing value, treating blank and absent as the same.
+ * @param {unknown} value Raw routing value.
+ * @returns {string} A comparable key, empty when nothing was declared.
+ */
+function normalize(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}