akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/exec/param-secrets.js

@@ -2,39 +2,12 @@
 // 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/.
 /**
- * Best-effort secret-shaped-param detection (PR #714 review round 2, #13).
- *
- * ## Why params are declared NON-SECRET
- *
- * A workflow's run params are attached to every unit prompt as structured
- * context (`buildUnitPrompt` substitutes them into the engine preamble's
- * `{{PARAMS_JSON}}` placeholder — prose instructions are never interpolated)
- * and, critically, are part of the unit's **input hash**. The prompt an executor runs
- * must be byte-identical to the one the hash was taken over — redacting a param
- * would change the prompt, break the input-hash contract, and make a resumed or
- * replayed run diverge from the original. So params CANNOT be redacted and are
- * declared **non-secret**: secrets belong in **env bindings** (`env:` refs),
- * which are carried by NAME ONLY through the plan and the hash preimage and are
- * resolved from the process environment at dispatch.
- *
- * This module is the loud, best-effort guardrail on top of that contract: it
- * scans params for values that LOOK like credentials (secret-suggesting key
- * names, long high-entropy strings, known token prefixes) and returns WARNING
- * strings. It is purely advisory — it NEVER blocks a run and NEVER mutates
- * params — and is surfaced when a run starts. False positives and false
- * negatives are expected; it is a nudge, not a scanner.
- *
- * ## Reused as `akm task explain`'s redaction check
- *
- * `src/commands/tasks/explain.ts` reuses this same heuristic (via its own
- * `isSecretShapedValue` wrapper) to decide which task-input values to print
- * as `"<redacted>"` instead of in full. That reuse does NOT upgrade this
- * detector into a hard guarantee: `explain`'s redaction is exactly as
- * best-effort as the warnings above — a short, low-entropy, or
- * unusually-named credential that this function does not flag prints
- * UNREDACTED there too. Do not describe either surface as "secret-free by
- * construction"; describe it as "secret-shaped values are redacted on a
- * best-effort basis."
+ * Best-effort secret-shaped-param detection. Run params reach every unit
+ * prompt in clear and are shown by `akm workflow status`; secrets belong in
+ * `env:` bindings. This scans params for credential-looking keys or values and
+ * returns warnings at run start (never blocking), and feeds the same values
+ * into the dispatch redaction set. `akm task explain` reuses the heuristic to
+ * redact input values — best-effort there too, never a guarantee.
  */
 /**
  * Substrings that, when present in a param KEY (case-insensitive), suggest the
@@ -84,32 +57,42 @@ function valueLooksSecret(value) {
     return false;
 }
 const MOVE_TO_ENV = "Workflow params are copied verbatim into every native unit execution context and returned in `akm workflow run` and " +
-    "`akm workflow status` output (they are part of the unit input hash and CANNOT be redacted) — move " +
-    "secrets to an env binding (`env:` ref), whose value native execution resolves only at dispatch instead of storing " +
-    "it as a run param.";
+    "`akm workflow status` output — move secrets to an env binding (`env:` ref), whose value native execution resolves " +
+    "only at dispatch instead of storing it as a run param.";
 /**
- * Scan run params for secret-shaped values. Returns human-readable WARNING
- * strings (best-effort; never throws, never blocks). Recurses into nested
- * objects and arrays, reporting the dotted/indexed path of each hit. A key whose
- * NAME suggests a secret is flagged regardless of value shape; any string value
- * that LOOKS like a credential is flagged regardless of key name. Each path is
- * reported at most once.
+ * Scan run params (recursively) for secret-suggesting key names or
+ * credential-looking string values; one warning per path. Never throws.
  */
 export function detectSecretShapedParams(params) {
     const warnings = [];
     const seen = new Set();
-    const push = (path, why) => {
+    walkSecretShaped(params, (path, why) => {
         if (seen.has(path))
             return;
         seen.add(path);
         warnings.push(`Run param "${path}" ${why}. ${MOVE_TO_ENV} (Heuristic warning; params are declared non-secret.)`);
-    };
+    });
+    return warnings;
+}
+/**
+ * The flagged string values, for the dispatch redaction set (values under 8
+ * characters are left out so `token_limit: "1000"` cannot blank out output).
+ */
+export function secretShapedParamValues(params) {
+    const values = new Set();
+    walkSecretShaped(params, (_path, _why, value) => {
+        if (typeof value === "string" && value.trim().length >= 8)
+            values.add(value);
+    });
+    return [...values];
+}
+function walkSecretShaped(params, hit) {
     const walk = (value, path, key) => {
         if (key !== null && keyLooksSecret(key))
-            push(path, "has a secret-suggesting name");
+            hit(path, "has a secret-suggesting name", value);
         if (typeof value === "string") {
             if (valueLooksSecret(value))
-                push(path, "has a secret-shaped value (long, high-entropy string)");
+                hit(path, "has a secret-shaped value (long, high-entropy string)", value);
             return;
         }
         if (Array.isArray(value)) {
@@ -125,5 +108,4 @@ export function detectSecretShapedParams(params) {
     };
     for (const [k, v] of Object.entries(params))
         walk(v, k, k);
-    return warnings;
 }