akm-cli 0.8.0-rc1 → 0.8.0

package/dist/commands/info.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { getAssetTypes } from "../core/asset-spec";
 import { getSources, loadConfig } from "../core/config";

package/dist/commands/init.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * akm initialization logic.
  *
@@ -9,10 +12,55 @@ import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "../core/asset-spec";
 import { loadUserConfig, saveConfig } from "../core/config";
-import { getBinDir, getConfigPath, getDefaultStashDir } from "../core/paths";
+import { ConfigError } from "../core/errors";
+import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../core/paths";
 import { ensureRg } from "../setup/ripgrep-install";
+/**
+ * Refuse to persist a temporary-directory stashDir to the user's config when
+ * running under a test runner AND `--dir <tempdir>` was passed explicitly.
+ * This guard targets the exact agent-overreach pattern documented in
+ * `memory:akm-init-persists-stashdir-warning`: an agent ran
+ * `akm init --dir $(mktemp -d)` for an E2E test and silently rewrote the
+ * developer's real config to point at a now-deleted temp dir.
+ *
+ * Tests that legitimately resolve a tempdir via HOME (default-path init) are
+ * unaffected — those are normal `~/akm` resolutions and not the failure mode.
+ *
+ * Test sentinels (either suffices):
+ *   - `BUN_TEST=1`     — explicit opt-in
+ *   - `NODE_ENV=test`  — what `bun test` sets today
+ *
+ * Tests that genuinely need to exercise `akm init --dir /tmp/...` should set
+ * `AKM_FORCE_INIT_TMP_STASH=1`.
+ */
+function assertInitSandbox(stashDir, dirExplicitlyProvided) {
+    if (!dirExplicitlyProvided)
+        return; // Only guard explicit --dir, not default HOME resolution.
+    const isUnderTest = process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+    if (!isUnderTest)
+        return;
+    if (process.env.AKM_FORCE_INIT_TMP_STASH === "1")
+        return;
+    const isTmp = stashDir.startsWith("/tmp/") ||
+        stashDir === "/tmp" ||
+        stashDir.startsWith("/var/tmp/") ||
+        stashDir === "/var/tmp" ||
+        stashDir.startsWith("/private/var/folders/") ||
+        stashDir.startsWith("/private/tmp/");
+    if (!isTmp)
+        return;
+    throw new ConfigError(`refusing to persist --dir stashDir to a temporary path while under test runner; set AKM_FORCE_INIT_TMP_STASH=1 if you really mean it (stashDir=${stashDir})`, "INIT_TMP_STASH_REFUSED");
+}
 export async function akmInit(options) {
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
+    // Safety check (#473): refuse stashDir at /, $HOME, /etc, ~/.config, etc.
+    // Runs BEFORE any disk write — a fat-fingered `akm init --dir /` or
+    // `akm init --dir ~` would otherwise mkdir + git-init the user's system
+    // root or home directory. Catastrophic-on-misuse vs. trivial-to-recover-from.
+    assertSafeStashDir(stashDir);
+    // Defense-in-depth: refuse to persist an explicit --dir /tmp/... stashDir
+    // to config under a test runner. Default HOME-resolved paths are exempt.
+    assertInitSandbox(stashDir, options?.dir != null);
     let created = false;
     if (!fs.existsSync(stashDir)) {
         fs.mkdirSync(stashDir, { recursive: true });

package/dist/commands/installed-stashes.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Source operations: list, remove, update.
  *
@@ -16,7 +19,6 @@ import { parseGitRepoUrl, syncMirroredRepo } from "../sources/providers/git";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror } from "../sources/website-ingest";
 import { listWikis, resolveWikisRoot } from "../wiki/wiki";
-import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailureForAction, } from "./install-audit";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
 import { removeStash } from "./source-manage";
 export async function akmListSources(input) {
@@ -196,29 +198,11 @@ async function updateWebsiteSource(stashDir, target, all, websiteSource) {
     return buildUpdateResponse(stashDir, target, all, []);
 }
 /** Sync a single installed registry entry and return the processed record. */
-async function updateRegistryEntry(entry, force, auditConfig) {
+async function updateRegistryEntry(entry, force) {
     if (force && shouldCleanupCache(entry)) {
         cleanupDirectoryBestEffort(entry.cacheDir);
     }
     const synced = await syncFromRef(entry.ref, { force });
-    // Mirror the post-sync audit hook from akmAdd so `akm update` can't
-    // silently land malicious content during refresh.
-    const registryLabels = deriveRegistryLabels({
-        source: synced.source,
-        ref: synced.ref,
-        artifactUrl: synced.artifactUrl,
-    });
-    enforceRegistryInstallPolicy(registryLabels, auditConfig, entry.ref);
-    const audit = auditInstallCandidate({
-        rootDir: synced.extractedDir,
-        source: synced.source,
-        ref: synced.ref,
-        registryLabels,
-        config: auditConfig,
-    });
-    if (audit.blocked) {
-        throw new UsageError(formatInstallAuditFailureForAction(synced.ref, audit, "update"), "INVALID_FLAG_VALUE", `Re-run with \`akm update ${synced.ref} --trust\` only if you intentionally trust this source.`);
-    }
     const installedEntry = {
         id: synced.id,
         source: synced.source,
@@ -255,7 +239,7 @@ async function updateRegistryEntry(entry, force, auditConfig) {
             resolvedRevision: entry.resolvedRevision,
             cacheDir: entry.cacheDir,
         },
-        installed: { ...installedEntry, extractedDir: synced.extractedDir, audit },
+        installed: { ...installedEntry, extractedDir: synced.extractedDir },
         changed: {
             version: versionChanged,
             revision: revisionChanged,
@@ -315,10 +299,9 @@ export async function akmUpdate(input) {
             return updateWebsiteSource(stashDir, target, all, websiteMatch);
     }
     const selectedEntries = selectTargets(installedEntries, target, all);
-    const auditConfig = config;
     const processed = [];
     for (const entry of selectedEntries) {
-        processed.push(await updateRegistryEntry(entry, force, auditConfig));
+        processed.push(await updateRegistryEntry(entry, force));
     }
     return buildUpdateResponse(stashDir, target, all, processed);
 }

package/dist/commands/knowledge.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Knowledge-command helpers extracted from `src/cli.ts`.
  *

package/dist/commands/lint/agent-linter.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { BaseLinter } from "./base-linter";
 /**

package/dist/commands/lint/base-linter.js

@@ -1,5 +1,35 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+// CONTRACT: ref-resolver
+// ----------------------------------------------------------------------------
+// The `refExistsInAnyStash` and `refToRelPath` helpers below are contract-
+// locked: a sister copy lives in the akm-plugins repo at
+// `shared/ref-extraction.ts` (and the runtime-shipped duplicate at
+// `claude/shared/ref-extraction.ts`). Both implementations resolve the same
+// `<type>:<slug>` -> on-disk-asset question and MUST agree on the set of
+// reachable refs for any given stash layout.
+//
+// The lock is enforced by `tests/contracts/ref-resolver-contract.test.ts`,
+// which drives this implementation through a canonical fixture set. The
+// akm-plugins repo ships an equivalent test that drives its copy through the
+// SAME inputs and asserts identical outcomes. Any change to the resolver
+// behavior on either side MUST update both contract tests in lockstep, or one
+// will fail.
+//
+// Cases the contract covers (see fixture in the contract test):
+//   - existing memory / knowledge / agent / workflow / skill / vault refs
+//   - knowledge subdirectory layout (knowledge/<category>/<slug>.md)
+//   - skill multi-file layout (skills/<slug>/SKILL.md)
+//   - memory `.derived.md` sibling
+//   - vault default vs named (.env vs <name>.env)
+//   - namespaced slugs containing `/`
+//   - non-existent refs
+//   - script type (unresolvable by design — both must return false)
+// ----------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
+import { findSafeInsertionPoint } from "./markdown-insertion";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function formatDate(d) {
     const y = d.getFullYear();
@@ -56,8 +86,12 @@ function checkStalePath(body) {
 }
 // ── missing-ref helpers ───────────────────────────────────────────────────────
 const REF_RE = /(?:^|[\s`"'(])((agent|command|knowledge|memory|script|skill|workflow|lesson|task|wiki|vault):[^\s"'`)\]>,\n]+)/gm;
-/** Map from ref type to relative path pattern within stashRoot. Returns null to skip. */
-function refToRelPath(refType, refName) {
+/**
+ * Map from ref type to relative path pattern within stashRoot. Returns null to skip.
+ *
+ * Exported for contract testing — see header CONTRACT block.
+ */
+export function refToRelPath(refType, refName) {
     switch (refType) {
         case "agent":
             return path.join("agents", `${refName}.md`);
@@ -80,7 +114,13 @@ function refToRelPath(refType, refName) {
         case "wiki":
             return path.join("wikis", `${refName}.md`);
         case "vault":
-            return path.join("vaults", `${refName}.md`);
+            // Vaults are .env files. The canonical name "default" (or empty) maps to
+            // ".env"; any other name maps to "<name>.env".  This mirrors the vault
+            // asset-spec toAssetPath logic in src/core/asset-spec.ts.
+            if (!refName || refName === "default") {
+                return path.join("vaults", ".env");
+            }
+            return path.join("vaults", `${refName}.env`);
         default:
             return null;
     }
@@ -88,8 +128,10 @@ function refToRelPath(refType, refName) {
 /**
  * Returns true if `relPath` resolves to a real file (or multi-file directory
  * primary) in ANY of the provided stash roots.
+ *
+ * Exported for contract testing — see header CONTRACT block.
  */
-function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
+export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
     for (const root of stashRoots) {
         const absPath = path.join(root, relPath);
         if (fs.existsSync(absPath))
@@ -104,6 +146,23 @@ function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
             if (fs.existsSync(derivedPath))
                 return true;
         }
+        // Knowledge-specific: search subdirectories like knowledge/projects/, knowledge/tools/, etc.
+        if (refType === "knowledge") {
+            try {
+                const knowledgeDir = path.join(root, "knowledge");
+                if (fs.existsSync(knowledgeDir) && fs.statSync(knowledgeDir).isDirectory()) {
+                    const entries = fs.readdirSync(knowledgeDir);
+                    for (const entry of entries) {
+                        const subPath = path.join(knowledgeDir, entry, `${refName}.md`);
+                        if (fs.existsSync(subPath))
+                            return true;
+                    }
+                }
+            }
+            catch {
+                // Ignore errors reading directory
+            }
+        }
         // Fallback: the refName may already encode the full stash-relative path
         // (e.g. knowledge:skills/foo/references/bar where the file lives at
         // <stash>/skills/foo/references/bar.md, not <stash>/knowledge/skills/...).
@@ -119,6 +178,11 @@ function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
 /**
  * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
  * body that does not resolve to a real file under any of the provided stash roots.
+ *
+ * Skips false-positive patterns:
+ * - Shell variables: memory:$(cmd) or knowledge:${VAR}
+ * - ACP type notation: agent::Type (double colons are C++/ACP syntax)
+ * - Incomplete/placeholder refs: slug is single character or "**"
  */
 function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
     const allRoots = [stashRoot, ...extraStashRoots];
@@ -128,6 +192,14 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = re.exec(body)) !== null) {
         const fullRef = match[1]; // e.g. "workflow:foo" or "local//workflow:foo"
+        // Skip shell variables: memory:$(cmd) or knowledge:${VAR}
+        if (fullRef.includes("$(") || fullRef.includes("${")) {
+            continue;
+        }
+        // Skip ACP type notation: agent::Type (double colons)
+        if (fullRef.includes("::")) {
+            continue;
+        }
         // Strip leading "local//" prefix if present
         let ref = fullRef;
         if (ref.startsWith("local//")) {
@@ -147,6 +219,10 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
         if (!refName || refName.startsWith("/") || refName.startsWith("~") || refName.startsWith("http")) {
             continue;
         }
+        // Skip placeholder/incomplete refs: single character slug or "**"
+        if (refName.length <= 1 || refName === "**") {
+            continue;
+        }
         const relPath = refToRelPath(refType, refName);
         if (relPath === null)
             continue; // type is skipped
@@ -156,6 +232,113 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
     }
     return missing;
 }
+// ── frontmatter refs ─────────────────────────────────────────────────────────
+/**
+ * Return the `refs:` array from frontmatter when it is present and is an
+ * array of strings; otherwise return `null` to signal the caller should
+ * fall back to scanning the body. An empty array (`refs: []`) is also
+ * treated as authoritative — it explicitly declares "this asset has no
+ * outbound refs" and suppresses the body scan.
+ *
+ * The `refs:` frontmatter key is used by the claude-code session-capture
+ * hook (see `shared/ref-extraction.ts` in the akm-plugins repo) to
+ * persist a validated outbound-ref list alongside the raw transcript.
+ * Hand-written memories rarely populate this key — for those the body
+ * scan remains the source of truth.
+ *
+ * Session-checkpoint memories use a nested frontmatter pattern: `akm
+ * remember` wraps the file in `---\n…\n---` and the hook's own
+ * `---\nakm_memory_kind: session_checkpoint\n…\n---` block is preserved
+ * inside the body. We look in both places so the `refs:` key works
+ * regardless of where the producer wrote it.
+ */
+function extractFrontmatterRefs(data, body) {
+    const fromOuter = readRefsArray(data.refs);
+    if (fromOuter !== null)
+        return fromOuter;
+    const innerData = parseInnerFrontmatterBlock(body);
+    if (innerData) {
+        const fromInner = readRefsArray(innerData.refs);
+        if (fromInner !== null)
+            return fromInner;
+    }
+    return null;
+}
+function readRefsArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === "string" && entry.trim())
+            out.push(entry.trim());
+    }
+    return out;
+}
+/**
+ * Detect a leading nested frontmatter block in `body` (i.e. a `---\n…\n---`
+ * pair that opens within the first few lines of the body). When present,
+ * parse a minimal subset of YAML — top-level scalars and block-list
+ * arrays — sufficient to recognise the `refs:` key. Anything fancier is
+ * silently ignored.
+ *
+ * This is a deliberately narrow parser: lint must never throw on
+ * unexpected YAML, and the only key we care about here is `refs:`.
+ */
+function parseInnerFrontmatterBlock(body) {
+    // Skip up to three blank/header lines, then require `---` to open the block.
+    const lines = body.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length && i < 3 && lines[i].trim() === "")
+        i += 1;
+    if (lines[i] !== "---")
+        return null;
+    const open = i;
+    let close = -1;
+    for (let j = open + 1; j < lines.length; j += 1) {
+        if (lines[j] === "---") {
+            close = j;
+            break;
+        }
+    }
+    if (close === -1)
+        return null;
+    const block = lines.slice(open + 1, close);
+    const data = {};
+    let currentKey = null;
+    let currentList = null;
+    for (const line of block) {
+        const listItem = line.match(/^(?: {2})?- (.*)$/);
+        if (listItem && currentList) {
+            currentList.push(listItem[1].trim().replace(/^["'](.*)["']$/, "$1"));
+            continue;
+        }
+        const inlineFlow = line.match(/^(\w[\w-]*):\s*\[(.*)\]\s*$/);
+        if (inlineFlow) {
+            currentKey = inlineFlow[1];
+            const items = inlineFlow[2]
+                .split(",")
+                .map((s) => s.trim().replace(/^["'](.*)["']$/, "$1"))
+                .filter(Boolean);
+            data[currentKey] = items;
+            currentList = null;
+            continue;
+        }
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (!kv)
+            continue;
+        currentKey = kv[1];
+        const value = kv[2].trim();
+        if (value === "") {
+            currentList = [];
+            data[currentKey] = currentList;
+        }
+        else {
+            data[currentKey] = value.replace(/^["'](.*)["']$/, "$1");
+            currentList = null;
+        }
+    }
+    return data;
+}
 // ── BaseLinter ────────────────────────────────────────────────────────────────
 /**
  * Abstract base class providing the two cross-type checks shared by all asset
@@ -167,6 +350,35 @@ function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
  * (in practice the base class updates `ctx.raw` in place when `fix` is true).
  */
 export class BaseLinter {
+    /**
+     * Insert one or more lines into a markdown body at a safe location.
+     *
+     * "Safe" means: not inside a markdown table, HTML table, fenced code block,
+     * or indented code block. If `proposedLineNumber` falls inside one of those
+     * regions, the helper pushes the insertion to immediately after the region.
+     * This is a regression guard against the class of bug where an auto-fix
+     * splits a table fence by injecting a callout between the separator row
+     * and the first data row (broke `knowledge/akm-cli-reference.md` in 0.8.0).
+     *
+     * Subclasses that perform line-based body insertion MUST route through this
+     * helper instead of calling `splice` directly. Insertion fixers must NOT
+     * touch frontmatter — use `fixMissingUpdated` / `fixUnquotedColon` style
+     * regex edits for that case (those already operate inside the `---…---`
+     * fence and don't intersect with body line numbers).
+     *
+     * @param raw                 Full file contents (frontmatter + body).
+     * @param newLines            Lines to insert (without trailing newlines).
+     * @param proposedLineNumber  0-based line index within `raw` where the
+     *                            caller wants the new content to appear.
+     * @returns The mutated file contents with `newLines` spliced at the
+     *          adjusted safe position.
+     */
+    insertLinesSafely(raw, newLines, proposedLineNumber) {
+        const lines = raw.split(/\r?\n/);
+        const safeIdx = findSafeInsertionPoint(lines, proposedLineNumber);
+        lines.splice(safeIdx, 0, ...newLines);
+        return lines.join("\n");
+    }
     runBaseChecks(ctx) {
         const issues = [];
         let currentRaw = ctx.raw;
@@ -237,7 +449,23 @@ export class BaseLinter {
             });
         }
         // ── 4. missing-ref ─────────────────────────────────────────────────────
-        const missingRefs = checkMissingRefs(ctx.body, ctx.stashRoot, ctx.extraStashRoots);
+        // Carve-out for assets that declare an explicit `refs:` array in
+        // frontmatter (e.g. session-checkpoint memories captured by the
+        // claude-code hook). The frontmatter array is the *authoritative*
+        // ref list — any ref-shaped tokens in the body are treated as
+        // literal strings (heredocs, grep patterns, JSON values, regex
+        // patterns embedded in tool transcripts). Without this carve-out
+        // every session capture produces a fresh batch of `missing-ref`
+        // flags on every literal `<type>:<slug>` token in a transcript.
+        //
+        // The producer guarantees that entries in `refs:` already resolve
+        // (it validates against the live stash before writing), so we
+        // still run `checkMissingRefs` against the array itself to catch
+        // refs that were valid at capture time but later removed from the
+        // stash.
+        const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
+        const refSource = explicitRefs !== null ? explicitRefs.join("\n") : ctx.body;
+        const missingRefs = checkMissingRefs(refSource, ctx.stashRoot, ctx.extraStashRoots);
         for (const { ref, resolvedRelPath } of missingRefs) {
             issues.push({
                 file: ctx.relPath,

package/dist/commands/lint/command-linter.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { BaseLinter } from "./base-linter";
 /**

package/dist/commands/lint/default-linter.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { BaseLinter } from "./base-linter";
 /**
  * Default linter for asset types that have no type-specific rules beyond the

package/dist/commands/lint/env-key-rules.js

@@ -0,0 +1,154 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Vault security lint rules — flags known-dangerous environment variable names.
+ *
+ * These env var names, when present as vault keys, indicate the vault can be
+ * used to hijack process execution via loader injection, path override, or
+ * shell/runtime startup hooks.  The lint pass emits a warning-level finding;
+ * it does NOT block vault load or `akm vault setKey`.
+ *
+ * Enforcement scope:
+ *   - `akm lint` reports findings as `dangerous-vault-key` (non-blocking warn).
+ *   - `akm add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
+ *     the user explicitly confirms at the prompt).
+ *   - `akm vault setKey` does NOT consult this list — by design, the operator
+ *     owns their own vault and may legitimately store any key locally.  The
+ *     gate exists only for third-party stash installation.
+ *
+ * False-positive tradeoff:
+ *   A handful of keys (EDITOR, VISUAL, PAGER) are included because they are
+ *   invoked by many interactive tools and are a documented RCE vector when
+ *   sourced from untrusted vaults.  They will also flag on benign vaults
+ *   where the operator legitimately wants to set their editor — accept the
+ *   FP and bypass with `--allow-insecure` after review.
+ */
+import { listKeys } from "../env";
+// ── Dangerous key set ─────────────────────────────────────────────────────────
+export const DANGEROUS_VAULT_KEYS = new Set([
+    // Dynamic linker hijacking (Linux glibc ld.so)
+    "LD_PRELOAD", // forces shared library injection
+    "LD_LIBRARY_PATH", // overrides library search path
+    "LD_AUDIT", // loads auditing libs (CVE-class injection vector)
+    "LD_DEBUG", // info disclosure / loader behaviour leak
+    "LD_BIND_NOW", // eager symbol resolution — can trigger malicious libs
+    "LD_PROFILE", // writes profile data — abusable for info disclosure
+    "LD_ASSUME_KERNEL", // kernel-version spoofing affecting loader behaviour
+    "LD_TRACE_LOADED_OBJECTS", // info disclosure (lists linked libs)
+    // Dynamic linker hijacking (macOS dyld)
+    "DYLD_INSERT_LIBRARIES", // macOS analogue of LD_PRELOAD
+    "DYLD_LIBRARY_PATH", // overrides dyld library search path
+    "DYLD_FRAMEWORK_PATH", // overrides framework search path
+    // Shell and command resolution
+    "PATH", // command lookup hijack
+    "BASH_ENV", // sourced on non-interactive bash startup (RCE)
+    "ENV", // sourced on POSIX sh startup (RCE)
+    "PROMPT_COMMAND", // command run before each bash prompt (RCE)
+    "PS1", // prompt — command substitution arbitrary code
+    "PS2", // continuation prompt — command substitution
+    "IFS", // Internal Field Separator — classic word-splitting attack
+    // Shell startup hijack
+    "ZDOTDIR", // zsh startup file lookup directory hijack
+    // Language runtime hijacking — Node.js
+    "NODE_OPTIONS", // injects flags incl. --require module-load RCE
+    "NODE_PATH", // module resolution hijack
+    "NODE_TLS_REJECT_UNAUTHORIZED", // silently disables TLS verification — MITM enabler
+    // Language runtime hijacking — Python
+    "PYTHONSTARTUP", // sourced by interactive python (RCE)
+    "PYTHONPATH", // module resolution hijack
+    "PYTHONINSPECT", // drops into REPL after script — sandbox escape vector
+    "PYTHONHOME", // python install prefix hijack
+    "PYTHONNOUSERSITE", // disables user-site isolation — sandbox weakening
+    // Language runtime hijacking — Ruby
+    "RUBYLIB", // ruby load path hijack
+    "RUBYOPT", // injects ruby command-line opts
+    // Language runtime hijacking — Perl
+    "PERL5LIB", // perl @INC hijack
+    "PERL5OPT", // injects perl command-line opts
+    // Language runtime hijacking — Java
+    "JAVA_TOOL_OPTIONS", // honoured by every JVM — flag injection / agent load
+    "JDK_JAVA_OPTIONS", // JDK launcher options injection
+    "_JAVA_OPTIONS", // legacy JVM options injection
+    // Git (RCE via git invocations)
+    "GIT_SSH_COMMAND", // replaces ssh with arbitrary command (RCE)
+    "GIT_EXTERNAL_DIFF", // runs arbitrary command during diff (RCE)
+    "GIT_PAGER", // runs arbitrary command for paging (RCE)
+    "GIT_EDITOR", // runs arbitrary command for editor (RCE)
+    // Interactive-tool invocation hijack — high FP rate but documented RCE vectors
+    "EDITOR", // invoked by git, crontab, sudoedit, etc. (RCE)
+    "VISUAL", // EDITOR fallback used by many tools (RCE)
+    "PAGER", // invoked by git, man, systemctl, etc. (RCE)
+]);
+/**
+ * Pattern-based dangerous key matchers.
+ *
+ * Some attack vectors target a family of variable names rather than a single
+ * literal — most famously Shellshock (CVE-2014-6271), which exploits keys
+ * prefixed with `BASH_FUNC_`.  Listing every concrete name is impossible; we
+ * test against this pattern set in addition to the literal `Set`.
+ */
+export const DANGEROUS_VAULT_KEY_PATTERNS = [
+    {
+        // CVE-2014-6271 (Shellshock) — bash imports exported functions named
+        // `BASH_FUNC_<name>%%` and parses their bodies, enabling RCE.
+        pattern: /^BASH_FUNC_/,
+        reason: "Shellshock-class bash function injection (CVE-2014-6271)",
+    },
+];
+/**
+ * Returns `true` if the given key name is dangerous — either by literal match
+ * against `DANGEROUS_VAULT_KEYS` or by matching any entry in
+ * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ */
+export function isDangerousVaultKey(key) {
+    if (DANGEROUS_VAULT_KEYS.has(key))
+        return true;
+    for (const { pattern } of DANGEROUS_VAULT_KEY_PATTERNS) {
+        if (pattern.test(key))
+            return true;
+    }
+    return false;
+}
+// ── Checker ───────────────────────────────────────────────────────────────────
+/**
+ * Inspect a vault `.env` file and return a lint finding for every key whose
+ * name appears in `DANGEROUS_VAULT_KEYS` or matches a pattern in
+ * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ *
+ * @param vaultPath  Absolute path to the `.env` file.
+ * @param relPath    Stash-relative path used as the `file` field in findings
+ *                   (e.g. `"vaults/prod.env"`).
+ * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
+ *                   the finding message.
+ */
+export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
+    const { keys } = listKeys(vaultPath);
+    const issues = [];
+    for (const key of keys) {
+        if (!isDangerousVaultKey(key))
+            continue;
+        issues.push({
+            file: relPath,
+            issue: "dangerous-vault-key",
+            detail: `Env key \`${key}\` can be used to hijack process execution when injected via \`akm env run\`. Ref: ${vaultRef}. Review this file before running \`akm env run\` commands against untrusted stashes.`,
+            fixed: false,
+        });
+    }
+    return issues;
+}
+// ── Env-neutral aliases ───────────────────────────────────────────────────────
+//
+// These primitives guard *environment variable injection*, which is shared by
+// the `env` asset type, whole-file `secret` injection, and the `akm add`
+// supply-chain gate. The original `*Vault*` names are retained above for
+// backward compatibility (and stable lint output) through the 0.8.x
+// deprecation window; new call sites should prefer the env-neutral names.
+/** Env-neutral alias of {@link DANGEROUS_VAULT_KEYS}. */
+export const DANGEROUS_ENV_KEYS = DANGEROUS_VAULT_KEYS;
+/** Env-neutral alias of {@link DANGEROUS_VAULT_KEY_PATTERNS}. */
+export const DANGEROUS_ENV_KEY_PATTERNS = DANGEROUS_VAULT_KEY_PATTERNS;
+/** Env-neutral alias of {@link isDangerousVaultKey}. */
+export const isDangerousEnvKey = isDangerousVaultKey;
+/** Env-neutral alias of {@link checkVaultForDangerousKeys}. */
+export const checkEnvForDangerousKeys = checkVaultForDangerousKeys;