@codyswann/lisa 2.331.2 → 2.332.0

package/package.json

@@ -115,7 +115,7 @@
     "brace-expansion": ">=5.0.9"
   },
   "name": "@codyswann/lisa",
-  "version": "2.331.2",
+  "version": "2.332.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": "2.331.2",
+  "version": "2.332.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": "2.331.2",
+  "version": "2.332.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/scripts/aws-bootstrap.mjs

@@ -0,0 +1,102 @@
+/**
+ * Turn the AWS bootstrap bundle into environment variables the AWS SDKs obey.
+ *
+ * `LISA_AWS_BOOTSTRAP_JSON` carries the agent's AWS identity as one JSON blob.
+ * Materializing it verbatim is not enough, because nothing reads that name:
+ * every AWS SDK and the CLI look for `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`, or for a profile.
+ *
+ * Writing profiles alone is also not enough, and that is the failure this
+ * module exists for. A Claude cloud container ships its own
+ * `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in the ambient environment, and
+ * **environment variables outrank profile files in the credential chain**. So a
+ * session with correctly written `~/.aws/credentials` still failed:
+ *
+ *     aws sts get-caller-identity
+ *     InvalidClientTokenId: The security token included in the request is invalid.
+ *
+ * Deriving the pair into the materialized env file fixes it, because that file
+ * is sourced into the session and the last export wins. Exporting over a
+ * variable this project did not set is a real intrusion, so it is deliberate,
+ * narrow, and never silent:
+ *
+ *   - only when the bundle actually parses and carries both halves
+ *   - never over a value the secret store itself supplies under those names,
+ *     which is a project stating an explicit intent
+ *   - recorded in the notes file, so the override is discoverable by the same
+ *     read-the-note path as any other credential
+ * @module aws-bootstrap
+ */
+
+/** The names every AWS SDK and the CLI actually read. */
+const ACCESS_KEY = "AWS_ACCESS_KEY_ID";
+const SECRET_KEY = "AWS_SECRET_ACCESS_KEY";
+const REGION = "AWS_DEFAULT_REGION";
+
+/** The bundle that carries the agent's identity. */
+export const BOOTSTRAP_KEY = "LISA_AWS_BOOTSTRAP_JSON";
+
+/**
+ * Read the bootstrap bundle, treating anything malformed as absent.
+ *
+ * A parse failure must not take materialization down with it: every other
+ * secret in the run is still valid and still needed, and a session with most of
+ * its credentials beats a session with none.
+ * @param {string} raw Bundle contents.
+ * @returns {object|null} Parsed bundle, or null.
+ */
+export function parseBootstrap(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive the AWS variables implied by an already-selected secret set.
+ *
+ * Returns only additions; the caller merges. Nothing here mutates its input,
+ * so a caller can decide what to do with the result — including reporting it.
+ * @param {Map<string, {value: string}>} selected Secrets by exact name.
+ * @returns {Map<string, {value: string, note: string}>} Derived variables.
+ */
+export function deriveAwsEnvironment(selected) {
+  const derived = new Map();
+  const bundle = parseBootstrap(selected.get(BOOTSTRAP_KEY)?.value);
+  if (!bundle) return derived;
+
+  const accessKeyId = bundle.accessKeyId ?? bundle.aws_access_key_id;
+  const secretAccessKey =
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key;
+  // Both halves or neither. Half a credential is not a weaker credential, it is
+  // a confusing failure — the SDK reports a signature error rather than a
+  // missing one.
+  if (!accessKeyId || !secretAccessKey) return derived;
+
+  // A project that stores these under their own names has said something
+  // explicit. Overriding that would be this module guessing against an operator.
+  if (selected.has(ACCESS_KEY) || selected.has(SECRET_KEY)) return derived;
+
+  const note =
+    `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. Exported ` +
+    `deliberately so it overrides any ambient ${ACCESS_KEY} the host injects — ` +
+    `environment variables outrank profile files in the AWS credential chain, ` +
+    `so without this a stale host value wins and every call fails with ` +
+    `InvalidClientTokenId. This is the assume-only bootstrap identity; real ` +
+    `work assumes a role from it.`;
+
+  derived.set(ACCESS_KEY, { value: String(accessKeyId), note });
+  derived.set(SECRET_KEY, { value: String(secretAccessKey), note });
+
+  const region = bundle.region ?? bundle.defaultRegion;
+  if (region && !selected.has(REGION)) {
+    derived.set(REGION, {
+      value: String(region),
+      note: `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access.`,
+    });
+  }
+  return derived;
+}

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

@@ -27,6 +27,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
+import { deriveAwsEnvironment } from "./aws-bootstrap.mjs";
 import { renderEnv, renderNotes } from "./envfile.mjs";
 import { fetchAll } from "./providers.mjs";
 import { materializedPaths, readConfig } from "./surfaces.mjs";
@@ -74,25 +75,47 @@ export function materialize(cfg = readConfig()) {
     );
   }
 
+  // The AWS bundle is stored as one JSON blob under a name no SDK reads, so
+  // the variables it implies are derived here. Without them a host-injected
+  // AWS_ACCESS_KEY_ID wins — environment variables outrank profile files in the
+  // credential chain — and every AWS call fails with InvalidClientTokenId even
+  // though the real credential materialized correctly.
+  const derived = deriveAwsEnvironment(selected);
+  for (const [name, entry] of derived) selected.set(name, entry);
+
   const { dir, valuesFile, notesFile } = materializedPaths(cfg.namespace);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   chmodSync(dir, 0o700);
   writeAtomic(valuesFile, renderEnv(selected));
   writeAtomic(notesFile, renderNotes(selected));
-  return { count: selected.size, dir };
+  return { count: selected.size, derived: derived.size, dir };
 }
 
 function main() {
   const cfg = readConfig();
   if (process.argv.includes("--dry-run")) {
     const selected = fetchAll(cfg);
+    // Derive here too, or the preview lies in the one place it matters most:
+    // the derived names are exactly the ones that override ambient host
+    // credentials, so omitting them hides the most surprising effect of the run
+    // and reports a smaller count than the real write produces.
+    for (const [name, entry] of deriveAwsEnvironment(selected)) {
+      selected.set(name, entry);
+    }
     const { dir } = materializedPaths(cfg.namespace);
     console.log(`would write ${selected.size} secret(s) to ${dir}`);
     console.log([...selected.keys()].sort().join("\n"));
     return;
   }
-  const { count, dir } = materialize(cfg);
+  const { count, derived, dir } = materialize(cfg);
   console.log(`materialized ${count} secret(s) and their notes into ${dir}`);
+  if (derived > 0) {
+    // Said out loud: this run exported variables the host may also have set.
+    console.log(
+      `  ${derived} AWS variable(s) derived from the bootstrap bundle, ` +
+        `overriding any ambient value`
+    );
+  }
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -300,6 +300,44 @@ function installReleaseTree(tool, binDir) {
   }
 }
 
+/**
+ * Install a pinned artifact that IS the binary, with no archive around it.
+ *
+ * Several tools worth pinning publish a raw executable rather than an archive —
+ * jq ships `jq-linux-amd64` and a `sha256sum.txt`, which is ideal material for a
+ * checksummed pin and fits none of the archive kinds.
+ *
+ * Without this the only entry that passes `assertPinned` is `release-zip`, which
+ * then fails at install when `unzip` is handed a binary. A manifest entry that
+ * validates and cannot install is worse than one that is rejected outright: the
+ * error arrives during provisioning rather than during review.
+ *
+ * There is no `binary` field here, deliberately — the download is the binary,
+ * so there is nothing inside it to name.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory to install into.
+ */
+function installReleaseBinary(tool, binDir) {
+  const temporary = join(binDir, `.${tool.name}-download`);
+  mkdirSync(temporary, { recursive: true });
+  try {
+    const artifact = join(temporary, tool.name);
+    execFileSync("curl", ["-fsSL", tool.url, "-o", artifact], {
+      stdio: "inherit",
+    });
+    // Verify before it reaches a directory on PATH. For this kind that ordering
+    // matters more than for the archives: the downloaded file is directly
+    // executable, so a wrong artifact placed first is a wrong artifact that can
+    // be run.
+    verifyChecksum(artifact, tool.sha256, tool.name);
+    execFileSync("install", ["-m", "0755", artifact, join(binDir, tool.name)], {
+      stdio: "inherit",
+    });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
 /**
  * Install a pinned global npm package.
  * @param {object} tool Manifest entry.
@@ -328,6 +366,8 @@ export function installTool(tool, binDir) {
   if (tool.install === "release-zip") installReleaseZip(tool, binDir);
   else if (tool.install === "release-tar") installReleaseTar(tool, binDir);
   else if (tool.install === "release-tree") installReleaseTree(tool, binDir);
+  else if (tool.install === "release-binary")
+    installReleaseBinary(tool, binDir);
   else installNpmGlobal(tool);
 }
 

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -354,6 +354,18 @@ export function assertPinned(tool) {
     }
     return;
   }
+  // The download IS the binary, so there is no `binary` path to require — but
+  // the checksum matters more here than anywhere else, because the artifact is
+  // directly executable rather than something that has to be unpacked first.
+  if (tool.install === "release-binary") {
+    if (!tool.url || !tool.sha256) {
+      throw new Error(
+        `${tool.name}: a release-binary install needs both url and sha256.\n` +
+          `A version bump must move the checksum in the same reviewed commit.`
+      );
+    }
+    return;
+  }
   if (tool.install === "npm-global") {
     if (!tool.package)
       throw new Error(`${tool.name}: npm-global install needs a package`);
@@ -361,6 +373,6 @@ export function assertPinned(tool) {
   }
   throw new Error(
     `${tool.name}: unknown install method "${tool.install}".\n` +
-      `Supported: release-zip, release-tar, release-tree, npm-global.`
+      `Supported: release-zip, release-tar, release-tree, release-binary, npm-global.`
   );
 }

package/plugins/lisa/skills/lisa-secrets-access/scripts/aws-bootstrap.mjs

@@ -0,0 +1,102 @@
+/**
+ * Turn the AWS bootstrap bundle into environment variables the AWS SDKs obey.
+ *
+ * `LISA_AWS_BOOTSTRAP_JSON` carries the agent's AWS identity as one JSON blob.
+ * Materializing it verbatim is not enough, because nothing reads that name:
+ * every AWS SDK and the CLI look for `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`, or for a profile.
+ *
+ * Writing profiles alone is also not enough, and that is the failure this
+ * module exists for. A Claude cloud container ships its own
+ * `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in the ambient environment, and
+ * **environment variables outrank profile files in the credential chain**. So a
+ * session with correctly written `~/.aws/credentials` still failed:
+ *
+ *     aws sts get-caller-identity
+ *     InvalidClientTokenId: The security token included in the request is invalid.
+ *
+ * Deriving the pair into the materialized env file fixes it, because that file
+ * is sourced into the session and the last export wins. Exporting over a
+ * variable this project did not set is a real intrusion, so it is deliberate,
+ * narrow, and never silent:
+ *
+ *   - only when the bundle actually parses and carries both halves
+ *   - never over a value the secret store itself supplies under those names,
+ *     which is a project stating an explicit intent
+ *   - recorded in the notes file, so the override is discoverable by the same
+ *     read-the-note path as any other credential
+ * @module aws-bootstrap
+ */
+
+/** The names every AWS SDK and the CLI actually read. */
+const ACCESS_KEY = "AWS_ACCESS_KEY_ID";
+const SECRET_KEY = "AWS_SECRET_ACCESS_KEY";
+const REGION = "AWS_DEFAULT_REGION";
+
+/** The bundle that carries the agent's identity. */
+export const BOOTSTRAP_KEY = "LISA_AWS_BOOTSTRAP_JSON";
+
+/**
+ * Read the bootstrap bundle, treating anything malformed as absent.
+ *
+ * A parse failure must not take materialization down with it: every other
+ * secret in the run is still valid and still needed, and a session with most of
+ * its credentials beats a session with none.
+ * @param {string} raw Bundle contents.
+ * @returns {object|null} Parsed bundle, or null.
+ */
+export function parseBootstrap(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive the AWS variables implied by an already-selected secret set.
+ *
+ * Returns only additions; the caller merges. Nothing here mutates its input,
+ * so a caller can decide what to do with the result — including reporting it.
+ * @param {Map<string, {value: string}>} selected Secrets by exact name.
+ * @returns {Map<string, {value: string, note: string}>} Derived variables.
+ */
+export function deriveAwsEnvironment(selected) {
+  const derived = new Map();
+  const bundle = parseBootstrap(selected.get(BOOTSTRAP_KEY)?.value);
+  if (!bundle) return derived;
+
+  const accessKeyId = bundle.accessKeyId ?? bundle.aws_access_key_id;
+  const secretAccessKey =
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key;
+  // Both halves or neither. Half a credential is not a weaker credential, it is
+  // a confusing failure — the SDK reports a signature error rather than a
+  // missing one.
+  if (!accessKeyId || !secretAccessKey) return derived;
+
+  // A project that stores these under their own names has said something
+  // explicit. Overriding that would be this module guessing against an operator.
+  if (selected.has(ACCESS_KEY) || selected.has(SECRET_KEY)) return derived;
+
+  const note =
+    `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. Exported ` +
+    `deliberately so it overrides any ambient ${ACCESS_KEY} the host injects — ` +
+    `environment variables outrank profile files in the AWS credential chain, ` +
+    `so without this a stale host value wins and every call fails with ` +
+    `InvalidClientTokenId. This is the assume-only bootstrap identity; real ` +
+    `work assumes a role from it.`;
+
+  derived.set(ACCESS_KEY, { value: String(accessKeyId), note });
+  derived.set(SECRET_KEY, { value: String(secretAccessKey), note });
+
+  const region = bundle.region ?? bundle.defaultRegion;
+  if (region && !selected.has(REGION)) {
+    derived.set(REGION, {
+      value: String(region),
+      note: `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access.`,
+    });
+  }
+  return derived;
+}

package/plugins/lisa/skills/lisa-secrets-access/scripts/materialize-secrets.mjs

@@ -27,6 +27,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
+import { deriveAwsEnvironment } from "./aws-bootstrap.mjs";
 import { renderEnv, renderNotes } from "./envfile.mjs";
 import { fetchAll } from "./providers.mjs";
 import { materializedPaths, readConfig } from "./surfaces.mjs";
@@ -74,25 +75,47 @@ export function materialize(cfg = readConfig()) {
     );
   }
 
+  // The AWS bundle is stored as one JSON blob under a name no SDK reads, so
+  // the variables it implies are derived here. Without them a host-injected
+  // AWS_ACCESS_KEY_ID wins — environment variables outrank profile files in the
+  // credential chain — and every AWS call fails with InvalidClientTokenId even
+  // though the real credential materialized correctly.
+  const derived = deriveAwsEnvironment(selected);
+  for (const [name, entry] of derived) selected.set(name, entry);
+
   const { dir, valuesFile, notesFile } = materializedPaths(cfg.namespace);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   chmodSync(dir, 0o700);
   writeAtomic(valuesFile, renderEnv(selected));
   writeAtomic(notesFile, renderNotes(selected));
-  return { count: selected.size, dir };
+  return { count: selected.size, derived: derived.size, dir };
 }
 
 function main() {
   const cfg = readConfig();
   if (process.argv.includes("--dry-run")) {
     const selected = fetchAll(cfg);
+    // Derive here too, or the preview lies in the one place it matters most:
+    // the derived names are exactly the ones that override ambient host
+    // credentials, so omitting them hides the most surprising effect of the run
+    // and reports a smaller count than the real write produces.
+    for (const [name, entry] of deriveAwsEnvironment(selected)) {
+      selected.set(name, entry);
+    }
     const { dir } = materializedPaths(cfg.namespace);
     console.log(`would write ${selected.size} secret(s) to ${dir}`);
     console.log([...selected.keys()].sort().join("\n"));
     return;
   }
-  const { count, dir } = materialize(cfg);
+  const { count, derived, dir } = materialize(cfg);
   console.log(`materialized ${count} secret(s) and their notes into ${dir}`);
+  if (derived > 0) {
+    // Said out loud: this run exported variables the host may also have set.
+    console.log(
+      `  ${derived} AWS variable(s) derived from the bootstrap bundle, ` +
+        `overriding any ambient value`
+    );
+  }
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -300,6 +300,44 @@ function installReleaseTree(tool, binDir) {
   }
 }
 
+/**
+ * Install a pinned artifact that IS the binary, with no archive around it.
+ *
+ * Several tools worth pinning publish a raw executable rather than an archive —
+ * jq ships `jq-linux-amd64` and a `sha256sum.txt`, which is ideal material for a
+ * checksummed pin and fits none of the archive kinds.
+ *
+ * Without this the only entry that passes `assertPinned` is `release-zip`, which
+ * then fails at install when `unzip` is handed a binary. A manifest entry that
+ * validates and cannot install is worse than one that is rejected outright: the
+ * error arrives during provisioning rather than during review.
+ *
+ * There is no `binary` field here, deliberately — the download is the binary,
+ * so there is nothing inside it to name.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory to install into.
+ */
+function installReleaseBinary(tool, binDir) {
+  const temporary = join(binDir, `.${tool.name}-download`);
+  mkdirSync(temporary, { recursive: true });
+  try {
+    const artifact = join(temporary, tool.name);
+    execFileSync("curl", ["-fsSL", tool.url, "-o", artifact], {
+      stdio: "inherit",
+    });
+    // Verify before it reaches a directory on PATH. For this kind that ordering
+    // matters more than for the archives: the downloaded file is directly
+    // executable, so a wrong artifact placed first is a wrong artifact that can
+    // be run.
+    verifyChecksum(artifact, tool.sha256, tool.name);
+    execFileSync("install", ["-m", "0755", artifact, join(binDir, tool.name)], {
+      stdio: "inherit",
+    });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
 /**
  * Install a pinned global npm package.
  * @param {object} tool Manifest entry.
@@ -328,6 +366,8 @@ export function installTool(tool, binDir) {
   if (tool.install === "release-zip") installReleaseZip(tool, binDir);
   else if (tool.install === "release-tar") installReleaseTar(tool, binDir);
   else if (tool.install === "release-tree") installReleaseTree(tool, binDir);
+  else if (tool.install === "release-binary")
+    installReleaseBinary(tool, binDir);
   else installNpmGlobal(tool);
 }
 

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -354,6 +354,18 @@ export function assertPinned(tool) {
     }
     return;
   }
+  // The download IS the binary, so there is no `binary` path to require — but
+  // the checksum matters more here than anywhere else, because the artifact is
+  // directly executable rather than something that has to be unpacked first.
+  if (tool.install === "release-binary") {
+    if (!tool.url || !tool.sha256) {
+      throw new Error(
+        `${tool.name}: a release-binary install needs both url and sha256.\n` +
+          `A version bump must move the checksum in the same reviewed commit.`
+      );
+    }
+    return;
+  }
   if (tool.install === "npm-global") {
     if (!tool.package)
       throw new Error(`${tool.name}: npm-global install needs a package`);
@@ -361,6 +373,6 @@ export function assertPinned(tool) {
   }
   throw new Error(
     `${tool.name}: unknown install method "${tool.install}".\n` +
-      `Supported: release-zip, release-tar, release-tree, npm-global.`
+      `Supported: release-zip, release-tar, release-tree, release-binary, npm-global.`
   );
 }

package/plugins/lisa-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/aws-bootstrap.mjs

@@ -0,0 +1,102 @@
+/**
+ * Turn the AWS bootstrap bundle into environment variables the AWS SDKs obey.
+ *
+ * `LISA_AWS_BOOTSTRAP_JSON` carries the agent's AWS identity as one JSON blob.
+ * Materializing it verbatim is not enough, because nothing reads that name:
+ * every AWS SDK and the CLI look for `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`, or for a profile.
+ *
+ * Writing profiles alone is also not enough, and that is the failure this
+ * module exists for. A Claude cloud container ships its own
+ * `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in the ambient environment, and
+ * **environment variables outrank profile files in the credential chain**. So a
+ * session with correctly written `~/.aws/credentials` still failed:
+ *
+ *     aws sts get-caller-identity
+ *     InvalidClientTokenId: The security token included in the request is invalid.
+ *
+ * Deriving the pair into the materialized env file fixes it, because that file
+ * is sourced into the session and the last export wins. Exporting over a
+ * variable this project did not set is a real intrusion, so it is deliberate,
+ * narrow, and never silent:
+ *
+ *   - only when the bundle actually parses and carries both halves
+ *   - never over a value the secret store itself supplies under those names,
+ *     which is a project stating an explicit intent
+ *   - recorded in the notes file, so the override is discoverable by the same
+ *     read-the-note path as any other credential
+ * @module aws-bootstrap
+ */
+
+/** The names every AWS SDK and the CLI actually read. */
+const ACCESS_KEY = "AWS_ACCESS_KEY_ID";
+const SECRET_KEY = "AWS_SECRET_ACCESS_KEY";
+const REGION = "AWS_DEFAULT_REGION";
+
+/** The bundle that carries the agent's identity. */
+export const BOOTSTRAP_KEY = "LISA_AWS_BOOTSTRAP_JSON";
+
+/**
+ * Read the bootstrap bundle, treating anything malformed as absent.
+ *
+ * A parse failure must not take materialization down with it: every other
+ * secret in the run is still valid and still needed, and a session with most of
+ * its credentials beats a session with none.
+ * @param {string} raw Bundle contents.
+ * @returns {object|null} Parsed bundle, or null.
+ */
+export function parseBootstrap(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive the AWS variables implied by an already-selected secret set.
+ *
+ * Returns only additions; the caller merges. Nothing here mutates its input,
+ * so a caller can decide what to do with the result — including reporting it.
+ * @param {Map<string, {value: string}>} selected Secrets by exact name.
+ * @returns {Map<string, {value: string, note: string}>} Derived variables.
+ */
+export function deriveAwsEnvironment(selected) {
+  const derived = new Map();
+  const bundle = parseBootstrap(selected.get(BOOTSTRAP_KEY)?.value);
+  if (!bundle) return derived;
+
+  const accessKeyId = bundle.accessKeyId ?? bundle.aws_access_key_id;
+  const secretAccessKey =
+    bundle.secretAccessKey ?? bundle.aws_secret_access_key;
+  // Both halves or neither. Half a credential is not a weaker credential, it is
+  // a confusing failure — the SDK reports a signature error rather than a
+  // missing one.
+  if (!accessKeyId || !secretAccessKey) return derived;
+
+  // A project that stores these under their own names has said something
+  // explicit. Overriding that would be this module guessing against an operator.
+  if (selected.has(ACCESS_KEY) || selected.has(SECRET_KEY)) return derived;
+
+  const note =
+    `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access. Exported ` +
+    `deliberately so it overrides any ambient ${ACCESS_KEY} the host injects — ` +
+    `environment variables outrank profile files in the AWS credential chain, ` +
+    `so without this a stale host value wins and every call fails with ` +
+    `InvalidClientTokenId. This is the assume-only bootstrap identity; real ` +
+    `work assumes a role from it.`;
+
+  derived.set(ACCESS_KEY, { value: String(accessKeyId), note });
+  derived.set(SECRET_KEY, { value: String(secretAccessKey), note });
+
+  const region = bundle.region ?? bundle.defaultRegion;
+  if (region && !selected.has(REGION)) {
+    derived.set(REGION, {
+      value: String(region),
+      note: `Derived from ${BOOTSTRAP_KEY} by lisa-secrets-access.`,
+    });
+  }
+  return derived;
+}