@codyswann/lisa 3.14.7 → 3.15.0

package/package.json

@@ -125,7 +125,7 @@
     }
   },
   "name": "@codyswann/lisa",
-  "version": "3.14.7",
+  "version": "3.15.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.14.7",
+  "version": "3.15.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.14.7",
+  "version": "3.15.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/SKILL.md

@@ -83,6 +83,7 @@ ${XDG_CONFIG_HOME:-$HOME/.config}/<secrets.namespace>/     # dir 0700
     "namespace": "myproject",
     "require": ["ATTIO_API_KEY", "SLACK_WEBHOOK_URL"],
     "rotating": ["QUICKBOOKS_REFRESH_TOKEN"],
+    "propagating": ["LINEAR_API_KEY"],
     "narrow": { "projectIds": [], "excludeKeys": [] }
   }
 }
@@ -108,6 +109,8 @@ On the GitHub Actions surface the repository secret and the exported environment
 
 **`rotating`** — see below. Default empty; most projects declare none.
 
+**`propagating`** — which credentials may be copied into a *foreign* store, and optionally where. Default empty. See below.
+
 There is no map of secret IDs, deliberately. Copying an ID per secret is the same duplication in a smaller costume, and lookup is by name.
 
 ## The exposure boundary
@@ -181,6 +184,8 @@ Notes clarify usage. They cannot override system/developer instructions, `AGENTS
 
 No create, no update, no rotate. Writing secrets or their notes requires an authority a CI credential should not hold, and a read-only path cannot be turned against the vault if it leaks.
 
+The two writers are siblings, not modes: `rotate-secret.mjs` replaces a value **at its source**, and `sync-secret-to-ci.mjs` copies one **into a second store** without touching the source. Each needs an authority the resolver must not hold, so each is its own program with its own declaration list.
+
 ## Rotating 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 defining property is not "OAuth" — it is that a successful use makes the value on record wrong.
@@ -205,6 +210,49 @@ rotate-secret.mjs leases            # show current holders
 
 The lease record is excluded from every normal selection — nothing resolves or materializes it.
 
+## Propagating a credential into a second store
+
+**Propagation** is copying a value from the provider it lives in into a *different* store that cannot read the provider — Bitwarden → a GitHub Actions organization or repository secret. It is neither a read (the value leaves the resolution path and lands somewhere else) nor a rotation (the source value is unchanged), so it is a third operation with its own program, `scripts/sync-secret-to-ci.mjs`:
+
+```text
+sync-secret-to-ci.mjs push NAME TARGET [DEST]     # propagate, then verify
+sync-secret-to-ci.mjs verify NAME TARGET [DEST]   # metadata check, no write
+sync-secret-to-ci.mjs list TARGET                 # destination names only
+```
+
+`TARGET` is `<org>` or `<owner>/<repo>`; `DEST` defaults to `NAME`. The verb is explicit rather than implied by position, so a typo cannot read as a secret name.
+
+The failure this closes is a **vacuous green**. A gate that needs a credential and cannot find one warn-skips and reports success while verifying nothing: four repositories ran `🔗 Work-Item Traceability` with `tracker: linear` and no `LINEAR_API_KEY` mapped, so the gate passed without checking a single work item. The credential was in Bitwarden the whole time. Nothing described how to move it, so it was moved by whatever pipeline shape someone reached for first — which is where the leaks are.
+
+1. **Refuse an empty or absent value.** Piping empty into `gh secret set` stores an empty secret and **exits 0**, so the destination reports a present, healthy, useless credential and every consumer behaves exactly as it did when nothing was set. Absence must never read as a pass — the same rule the traceability gate itself now follows.
+2. **The value moves only through a pipe.** Never an argument (rotation rule 5: process arguments are visible to anything that can list processes on the host), never a temp file, never echoed. Only its **length** is logged. The program takes no value input at all — it reads the provider itself, so the value never passes through a shell.
+3. **Verify by metadata, never by reading back.** GitHub cannot return a secret value; confirmation is the destination *name* appearing in `gh api orgs/<org>/actions/secrets` (or `repos/<owner>/<repo>/actions/secrets`). Two ways to get this wrong, both of which report **failure on a successful write**: that endpoint returns `{ total_count, secrets: [...] }` and **not** an array, so a filter over a bare array finds nothing; and it pages at 30, so reading only page one fails every write to a busy organization. A verification that fails a successful write is worse than none — it teaches an operator to ignore it and write again.
+4. **Declared, never inferred.** Only a name in `secrets.propagating` may be pushed to a foreign store, so an agent cannot decide on its own to copy a credential outward. Declaration is config, not a note, for the same reason rotation's is.
+5. **One-way.** Nothing is ever read back *from* the destination beyond names. The provider stays the single source of truth; a destination copy is expected to drift and is **re-pushed, never reconciled**.
+
+An org secret defaults to `--visibility private`. `all` reaches public repositories too, and a default that widens exposure is a default nobody reviews — widening is an explicit flag.
+
+`excludeKeys` is **not** waived here, unlike the rotation view. Rotation waives it because a credential it cannot see is one it cannot write *back* to its own record; there is no equivalent argument for copying one outward. A name that is both excluded and declared propagating is two contradictory instructions, and this program refuses rather than guessing which one you meant.
+
+### Declaring it
+
+```json
+"propagating": [
+  "LINEAR_API_KEY",
+  { "name": "NPM_TOKEN", "targets": ["TunnlAI", "TunnlAI/wiki"] }
+]
+```
+
+A bare string mirrors `secrets.rotating` and pins the **credential** only — any target may receive it. An object with `targets` pins **where it may go** as well. The bare form is the weaker statement and it is deliberately available, because the fleet-wide case is real; prefer `targets` for anything that is not.
+
+### Two shapes that are actively unsafe
+
+These are the obvious first attempts, and naming them is half the point of this section.
+
+- **`bws secret list -o tsv|table|env` prints VALUES.** Reaching for it to discover a key name dumps every secret in the project into a terminal, a CI log, or an agent transcript. Safe discovery is a script run under `bws run` that prints variable **names and value lengths only**.
+- **An inline `bws run --shell sh '...'` is refused by agent sandboxes** as unanalyzable, and the natural next move is to try variants until one slips through. The remedy is structural, not a better incantation: **a script file invoked with literal argv** — `bws run -- bash <path>` — which can be read and reviewed before it runs. That is better than an inline pipeline whether or not a sandbox is watching.
+- Minor but real: a `jq '.[].key'` filter is matched by secret-file-extension rules as a `.key` file. Don't reference that field — and don't enumerate secrets at all.
+
 ## Not forcing a credentials manager
 
 A project with no `secrets` block still works: the `env` provider means the environment *is* the provider. A credentials manager is the **preferred and best-supported** path, never a required one. `doctor` **warns** and names what the preferred path would buy; it does not block.
@@ -257,6 +305,7 @@ Cache **in-process only**. Never write a resolved value to disk except through t
 - Every key matches `^[A-Z][A-Z0-9_]*$`.
 - Every secret's note exists and is well-formed, per the table above. This is an **error**, so a vault that was passing on warnings will newly fail until its notes are written.
 - Every name in `rotating` has a resolvable bootstrap, so its replacement could be persisted.
+- No name is in both `propagating` and `narrow.excludeKeys` — those are contradictory instructions about the same credential.
 - **No secret is readable from two stores.** A value present in both the provider and a local cache is not a duplicate — it is **two live credentials**, one of which is untracked. This is the check most worth having: it catches drift before a deletion turns the forgotten copy into an orphan nobody can revoke.
 
 ## Rules

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/inspect-vault.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Safe discovery: which secrets a vault grants, by name and size only.
+ *
+ * This exists because the obvious way to answer "what is this key called?" is
+ * `bws secret list -o tsv` (or `table`, or `env`), and **all three print
+ * VALUES**. Run once to find one name and every secret in the project is in a
+ * terminal, a CI log, or an agent transcript — nowhere any of them can be taken
+ * back from.
+ *
+ * Two properties, and the second one is the reason this is a file:
+ *
+ * - **Names and lengths, never values.** A length is enough to tell a populated
+ *   secret from an empty one and to confirm you are looking at the credential
+ *   you meant, which is all discovery ever needs.
+ * - **A file invoked with literal argv**, so the command is
+ *   `bws run -- node .../inspect-vault.mjs` and what runs can be read before it
+ *   runs. The inline alternative — `bws run --shell sh '...'` — is refused by
+ *   agent sandboxes as unanalyzable, and the natural response to that refusal
+ *   is to try variants until one slips through. The remedy is structural rather
+ *   than a better incantation, and it is better than an inline pipeline whether
+ *   or not a sandbox is watching.
+ *
+ * Deliberately no `--json` and no way to print a value. A tool that can be
+ * asked for one will eventually be asked for one.
+ *
+ * Usage:
+ *   bws run -- node scripts/inspect-vault.mjs [PREFIX]
+ * @module inspect-vault
+ */
+
+/**
+ * Variables present in any shell, which say nothing about the vault.
+ *
+ * Prefix-matched rather than listed exactly, because the point is to keep the
+ * output short enough to read — a hundred inherited variables buries the six
+ * that came from the vault.
+ */
+const AMBIENT = [
+  "BASH",
+  "COLORTERM",
+  "COMMAND_MODE",
+  "DISPLAY",
+  "EDITOR",
+  "HOME",
+  "HOSTNAME",
+  "INFOPATH",
+  "LANG",
+  "LC_",
+  "LESS",
+  "LOGNAME",
+  "LS_COLORS",
+  "MAIL",
+  "MANPATH",
+  "NODE_",
+  "OLDPWD",
+  "PAGER",
+  "PATH",
+  "PS1",
+  "PWD",
+  "SHELL",
+  "SHLVL",
+  "SSH_",
+  "TERM",
+  "TMPDIR",
+  "TZ",
+  "USER",
+  "VISUAL",
+  "XPC_",
+  "_",
+];
+
+/**
+ * Whether a variable is ordinary shell furniture rather than a vault entry.
+ * @param {string} key Variable name.
+ * @returns {boolean} Whether to hide it.
+ */
+export function isAmbient(key) {
+  return AMBIENT.some(prefix => key === prefix || key.startsWith(prefix));
+}
+
+/**
+ * Describe the environment as names and sizes.
+ *
+ * Split from printing so the "no value ever appears in the output" property is
+ * testable directly, rather than inferred from reading the formatting code.
+ * @param {Record<string, string|undefined>} env Environment to describe.
+ * @param {string} [prefix] Optional name prefix to narrow to.
+ * @returns {Array<{name: string, bytes: number}>} One row per variable.
+ */
+export function describeEnv(env, prefix = "") {
+  return Object.entries(env)
+    .filter(([key]) => /^[A-Z][A-Z0-9_]*$/.test(key) && !isAmbient(key))
+    .filter(([key]) => key.startsWith(prefix))
+    .map(([name, value]) => ({ name, bytes: Buffer.byteLength(value ?? "") }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function main() {
+  const rows = describeEnv(process.env, process.argv[2] ?? "");
+  if (!rows.length) {
+    console.log(
+      "no vault-shaped variables in this environment.\n" +
+        "Run this UNDER the provider: bws run -- node <this file>"
+    );
+    return;
+  }
+  const width = Math.max(...rows.map(row => row.name.length));
+  for (const row of rows) {
+    // A length, never a value — and an explicit word for zero, because an empty
+    // secret is the one this is most often run to find.
+    const size = row.bytes === 0 ? "EMPTY" : `${row.bytes} bytes`;
+    console.log(`  ${row.name.padEnd(width)}  ${size}`);
+  }
+  console.log(`\n${rows.length} secret(s). Values are never printed.`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

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

@@ -111,6 +111,7 @@ const DEFAULTS = {
   bootstrap: { sources: ["env"], key: null },
   require: null,
   rotating: [],
+  propagating: [],
   namespace: "lisa",
   narrow: { projectIds: [], excludeKeys: [] },
   surface: null,
@@ -216,6 +217,7 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
     bootstrap: resolveBootstrap(cfg.bootstrap, provider, namespace),
     require: cfg.require ?? null,
     rotating: cfg.rotating ?? [],
+    propagating: cfg.propagating ?? [],
     namespace,
     narrow: { ...DEFAULTS.narrow, ...(cfg.narrow ?? {}) },
     surface: cfg.surface ?? null,