akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/env/secret-cli.js

@@ -11,23 +11,36 @@
  *
  * `akm secret` manages whole-file secrets under each stash's secrets/ directory.
  * Unlike env files (.env key/value), the ENTIRE file is the secret value. The bytes
- * are NEVER written to stdout or structured output. Values reach a command only
- * via `akm secret run` (injected into a child env var) or `akm secret path`
- * (the Docker /run/secrets + `_FILE` convention).
+ * are NEVER written to stdout or structured output. The only value-use path is
+ * `akm secret run` (injected into a child env var).
+ *
+ * `secret path` and `secret remove` were REMOVED in 0.9.0 (R-027 / D-49): an
+ * audit found `path` resolved the ref through the read-side, all-sources
+ * resolver while `remove` resolved it through the write-target resolver, so
+ * `akm secret path <ref>` and `akm secret remove <ref>` could silently name
+ * two DIFFERENT files when a ref existed in more than one stash — inspect one,
+ * delete the other. The owner's ruling was to drop both subcommands rather
+ * than reconcile the resolvers. A ref's file lives at `<bundle>/secrets/<name>`
+ * (matching the ref exactly, e.g. `secrets/deploy-key` -> `secrets/deploy-key`
+ * under a bundle root — `akm bundle list` prints each configured bundle's root
+ * path); locate or delete it directly, or consume its value without touching
+ * disk via `akm secret run <ref> <VAR> -- <command>`.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
-import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
+import { deriveCanonicalAssetName } from "../../core/asset/asset-placement.js";
 import { loadConfig } from "../../core/config/config.js";
-import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
+import { makeSecretRef, resolveSecretPath, resolveSecretWriteTarget, withEnvSecretWrite, } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { readStdin } from "../../runtime.js";
 import { buildChildEnv } from "./child-env.js";
+import { sensitiveMarkerPath } from "./marker-path.js";
 function parseKeyListFlag(raw) {
     if (raw === undefined)
         return undefined;
@@ -56,7 +69,7 @@ function listSecretsRecursive() {
                 if (entry.name.endsWith(".lock") || entry.name.endsWith(".sensitive"))
                     continue;
                 // A sibling `<name>.sensitive` marker suppresses listing.
-                if (fs.existsSync(`${full}.sensitive`))
+                if (fs.existsSync(sensitiveMarkerPath(full, "secret")))
                     continue;
                 const canonical = deriveCanonicalAssetName("secret", secretsDir, full);
                 if (!canonical)
@@ -71,7 +84,7 @@ function listSecretsRecursive() {
 const secretListCommand = defineJsonCommand({
     meta: {
         name: "list",
-        description: "List all secrets across all stashes by name (the file contents are never shown)",
+        description: "List all secrets across all bundles by name (the file contents are never shown)",
     },
     async run() {
         output("secret-list", { secrets: listSecretsRecursive() });
@@ -85,7 +98,7 @@ const secretSetCommand = defineJsonCommand({
     args: {
         ref: {
             type: "positional",
-            description: "Secret ref (flat name, e.g. secret:deploy-key or just deploy-key; use --path for a subdirectory)",
+            description: "Secret ref (flat name, e.g. secrets/deploy-key or just deploy-key; use --path for a subdirectory)",
             required: true,
         },
         path: {
@@ -94,10 +107,16 @@ const secretSetCommand = defineJsonCommand({
         },
         "from-file": { type: "string", description: "Read the value from this file (stored byte-exact)" },
         "from-env": { type: "string", description: "Read the value from the named environment variable" },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
+        },
     },
     async run({ args }) {
         const { setSecret } = await import("./secret.js");
-        const { name, absPath, source } = resolveSecretPath(args.ref, { subPath: getStringArg(args, "path") });
+        const { name, absPath, target, ref } = resolveSecretWriteTarget(args.ref, args.target, {
+            subPath: getStringArg(args, "path"),
+        });
         const fromEnv = args["from-env"];
         const fromFile = args["from-file"];
         if (fromEnv !== undefined && fromFile !== undefined) {
@@ -131,24 +150,8 @@ const secretSetCommand = defineJsonCommand({
             // byte-exact storage of multi-line material (PEM keys, certs).
             value = Buffer.from(stdinBuf.toString("utf8").replace(/\n$/, ""), "utf8");
         }
-        setSecret(absPath, value);
-        output("secret-set", { ref: makeSecretRef(name, source) });
-    },
-});
-const secretPathCommand = defineJsonCommand({
-    meta: {
-        name: "path",
-        description: "Print the absolute secret file path for the Docker `_FILE` convention, e.g. `MY_SECRET_FILE=$(akm secret path secret:deploy-key)`.",
-    },
-    args: {
-        ref: { type: "positional", description: "Secret ref", required: true },
-    },
-    async run({ args }) {
-        const { name, absPath, source } = resolveSecretPath(args.ref);
-        if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
-        }
-        process.stdout.write(`${absPath}\n`);
+        withEnvSecretWrite(target, { type: "secret", name }, "Update", [absPath], () => setSecret(absPath, value));
+        output("secret-set", { ref });
     },
 });
 const secretRunCommand = defineJsonCommand({
@@ -181,11 +184,10 @@ const secretRunCommand = defineJsonCommand({
         if (isDangerousEnvKey(varName)) {
             throw new UsageError(`Refusing to inject a secret into "${varName}": it is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`, "INVALID_FLAG_VALUE");
         }
-        const dashIndex = process.argv.indexOf("--");
-        if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
+        const command = getParsedInvocation().passthroughArgs();
+        if (command.length === 0) {
             throw new UsageError("Missing command. Usage: akm secret run <ref> <VAR> -- <command>");
         }
-        const command = process.argv.slice(dashIndex + 1);
         const { name, absPath, source } = resolveSecretPath(args.ref);
         if (!fs.existsSync(absPath)) {
             throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
@@ -216,46 +218,28 @@ const secretRunCommand = defineJsonCommand({
             }
             throw err;
         }
-        process.exit(result.status ?? 0);
-    },
-});
-const secretRemoveCommand = defineJsonCommand({
-    meta: { name: "remove", description: "Remove a secret (and its .sensitive marker, if any)" },
-    args: {
-        ref: { type: "positional", description: "Secret ref", required: true },
-        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
-    },
-    async run({ args }) {
-        const { name, absPath, source } = resolveSecretPath(args.ref);
-        const { confirmDestructive } = await import("../../cli/confirm.js");
-        const confirmed = await confirmDestructive(`Remove secret "${args.ref}"? This cannot be undone.`, {
-            yes: args.yes === true,
-        });
-        if (!confirmed) {
-            process.stderr.write("Aborted.\n");
-            return;
-        }
-        const { removeSecret } = await import("./secret.js");
-        if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
-        }
-        const removed = removeSecret(absPath);
-        output("secret-remove", { ref: makeSecretRef(name, source), removed });
+        // R-067: was `process.exit(result.status ?? 0)`, unconditional even on
+        // the success path — it skipped the `finally { await
+        // disposeDispatchResources(); }` cleanup in src/cli.ts's `runCommand`.
+        // Setting `process.exitCode` and returning still exits with the child's
+        // exact status once the event loop drains, but lets cleanup run first —
+        // same pattern `emitJsonError` (src/cli/shared.ts) already established.
+        process.exitCode = result.status ?? 0;
+        return;
     },
 });
 export const secretCommand = defineGroupCommand({
     meta: {
         name: "secret",
-        description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
+        description: "Manage secrets — one standalone sensitive value per file (an API token, a PEM private key, a TLS cert).\n\n" +
+            "Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`. A secret's file lives at `<bundle>/secrets/<name>` (`akm bundle list` shows bundle roots) — read or delete it there directly, or consume its value without writing it anywhere via `akm secret run <ref> <VAR> -- <command>`.",
     },
     subCommands: {
         list: secretListCommand,
-        path: secretPathCommand,
         run: secretRunCommand,
         set: secretSetCommand,
-        remove: secretRemoveCommand,
-    },
-    defaultRun() {
-        output("secret-list", { secrets: listSecretsRecursive() });
     },
+    // No `defaultRun`: bare `akm secret` is a usage error (exit 2), the canonical
+    // bare-group behavior — owner ruling 12. Run `akm secret list` for what the
+    // bare form used to print.
 });

package/dist/commands/env/secret.js

@@ -14,20 +14,26 @@
  *
  * Invariant: a secret's bytes must never be written to stdout, returned
  * through the indexer / `akm show` renderer, or any structured output channel.
- * The supported value-use paths are:
+ * The supported value-use path is:
  *
  *   - `akm secret run <ref> <VAR> -- <cmd>` — value injected into the child
  *     process env as `VAR=<value>` (see `readValue`).
- *   - `akm secret path <ref>` — print the file path so a command can read it
- *     itself (Docker `/run/secrets` + `_FILE` convention).
+ *
+ * `akm secret path <ref>` (print the file path for the Docker `/run/secrets` +
+ * `_FILE` convention) was removed in 0.9.0 alongside `akm secret remove` — an
+ * audit found the two resolved a ref through different stash-selection logic
+ * and could silently target different files. A ref's file still lives at
+ * `<stash>/secrets/<name>`; locate or delete it there directly.
  *
  * Values are stored as raw bytes (no quoting, multi-line allowed) so they
  * round-trip byte-exact, unlike env values which forbid literal newlines.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { writeFileAtomic } from "../../core/common.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../../core/file-lock.js";
+import { safeRealpath, writeFileAtomic } from "../../core/common.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
+import { getDataDir } from "../../core/paths.js";
 import { sleepSync } from "../../runtime.js";
 // ── Write-lock helper ─────────────────────────────────────────────────────────
 /**
@@ -37,19 +43,22 @@ import { sleepSync } from "../../runtime.js";
  * throw rather than silently proceeding.
  */
 export function withSecretLock(secretPath, fn) {
-    const lockPath = `${secretPath}.lock`;
+    const lockPath = secretLockPath(secretPath);
+    const lockDir = path.dirname(lockPath);
+    fs.mkdirSync(lockDir, { recursive: true, mode: 0o700 });
     const deadline = Date.now() + 5000;
-    while (!tryAcquireLockSync(lockPath, String(process.pid))) {
+    let ownership;
+    while (!ownership) {
+        ownership = tryAcquireLockSync(lockPath, createLockPayload());
+        if (ownership)
+            break;
         const probe = probeLock(lockPath);
-        if (probe.state === "stale") {
-            releaseLock(lockPath);
+        if (probe.state === "stale" && reclaimStaleLock(lockPath, probe)) {
             continue;
         }
         if (Date.now() > deadline) {
-            const holderHint = probe.state === "held"
-                ? ` Lock file ${lockPath} is held by live PID ${probe.holderPid}.`
-                : ` Lock file ${lockPath} could not be inspected.`;
-            throw new Error(`Could not acquire secret lock for ${secretPath} after 5s.${holderHint} Retry once any other akm secret operation finishes, or remove the stale lock file.`);
+            const holderHint = probe.state === "held" ? ` It is held by live PID ${probe.holderPid}.` : "";
+            throw new Error(`Could not acquire the secret write lock after 5s.${holderHint} Retry once any other akm secret operation finishes.`);
         }
         sleepSync(10);
     }
@@ -57,9 +66,15 @@ export function withSecretLock(secretPath, fn) {
         return fn();
     }
     finally {
-        releaseLock(lockPath);
+        releaseLock(ownership);
     }
 }
+export function secretLockPath(secretPath, platform = process.platform) {
+    const canonical = safeRealpath(secretPath);
+    const identity = platform === "win32" ? canonical.toLowerCase() : canonical;
+    const key = createHash("sha256").update(identity).digest("hex");
+    return path.join(getDataDir(), "secret-locks", `${key}.lock`);
+}
 // ── Atomic byte write ──────────────────────────────────────────────────────────
 function ensureParentDir(filePath) {
     const dir = path.dirname(filePath);
@@ -68,38 +83,8 @@ function ensureParentDir(filePath) {
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
- * Walk a `secrets/` directory and return the POSIX-relative names of every
- * secret file. Lock files (`*.lock`), sensitive markers (`*.sensitive`), and
- * secrets with a sibling `<name>.sensitive` marker are excluded. The file
- * bodies are NEVER read.
- */
-export function listNames(secretsRoot) {
-    if (!fs.existsSync(secretsRoot))
-        return [];
-    const names = [];
-    const walk = (dir) => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            if (entry.name.endsWith(".lock") || entry.name.endsWith(".sensitive"))
-                continue;
-            // A sibling `<name>.sensitive` marker suppresses listing.
-            if (fs.existsSync(`${full}.sensitive`))
-                continue;
-            names.push(path.relative(secretsRoot, full).split(path.sep).join("/"));
-        }
-    };
-    walk(secretsRoot);
-    return names.sort();
-}
-/**
- * Read a secret's raw bytes. Internal use only (for `secret run` / `secret
- * path`). Callers MUST NOT write the returned value to stdout or any log.
+ * Read a secret's raw bytes. Internal use only (for `secret run`). Callers
+ * MUST NOT write the returned value to stdout or any log.
  */
 export function readValue(secretPath) {
     return fs.readFileSync(secretPath);
@@ -109,24 +94,9 @@ export function readValue(secretPath) {
  * mode 0600 under a write-lock. No quoting; multi-line / binary allowed.
  */
 export function setSecret(secretPath, value) {
-    ensureParentDir(secretPath);
     withSecretLock(secretPath, () => {
+        ensureParentDir(secretPath);
         // Mode 0600: secrets must never be world-readable, even transiently.
         writeFileAtomic(secretPath, value, 0o600);
     });
 }
-/**
- * Remove a secret file (and its `.sensitive` marker, if present). Returns true
- * if the secret existed.
- */
-export function removeSecret(secretPath) {
-    return withSecretLock(secretPath, () => {
-        if (!fs.existsSync(secretPath))
-            return false;
-        fs.rmSync(secretPath);
-        const marker = `${secretPath}.sensitive`;
-        if (fs.existsSync(marker))
-            fs.rmSync(marker);
-        return true;
-    });
-}