@yemi33/minions 0.1.1976 → 0.1.1978

package/docs/deprecated.json

@@ -1,4 +1,18 @@
 [
+  {
+    "id": "managed-spawn-env-allowlist",
+    "removedAt": "2026-05-18",
+    "reason": "ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist + envKeyAllowlistPrefixes removed; replaced by envKeyDenyPatterns + envKeyDenyOverrides. The allowlist shape required an engine PR for every new framework/project env prefix (W-mpbpa09c000rd513 tried per-project allowlist extension; user steered away — 'make sure that we are not hardcoding any env variables or being so rigid about it'). The denylist shape matches the actual credential-leakage threat model and lets plain project vars like CONSTELLATION_SERVER, DATABASE_URL, REDIS_HOST work with zero engine config while still blocking credential-shaped keys (AWS_*, *_TOKEN, *_SECRET, etc.). Per-project tightening is supported via project.managedSpawnExtraDenyPatterns (additive only, no per-project override list).",
+    "removedLocations": [
+      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist (15 keys)",
+      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlistPrefixes (8 prefixes)",
+      "engine/managed-spawn.js _envKeyAllowed (rewritten to deny+override+shape model)",
+      "engine/managed-spawn.js buildManagedSpawnHint (env-key guidance rewritten)",
+      "PR #2624 (closed, superseded — added per-project allowlist union; replaced here by per-project deny tightening)",
+      "test/unit/managed-spawn-validator.test.js 4e/4f/11a (rewritten for denylist semantics)"
+    ],
+    "notes": "Already removed in this PR; entry exists to track the breaking shape change in the deprecation log. Delete entry after 3 days per /cleanup-deprecated."
+  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:123-162",

package/docs/managed-spawn.md

@@ -36,7 +36,7 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
       "cmd": "bun",                          // must be on engine.managedSpawn.executableAllowlist
       "args": ["run", "dev"],                // ≤64 entries
       "cwd": "D:/repos/constellation",       // must be a real git worktree (requireGitWorkdir: true)
-      "env": { "VITE_HOST": "127.0.0.1" },   // ≤32 keys; allowlist + prefix-allowlist enforced
+      "env": { "CONSTELLATION_SERVER": "http://localhost:3000" },  // ≤32 keys; POSIX-shape + denylist enforced
       "ports": [3001],                       // 1024-65535; ≤20 per spec; advisory only (engine doesn't bind)
       "ttl_minutes": 240,                    // ≤1440 (24h hard cap); defaults to 240 (4h)
       "attrs": {                             // opaque per-spec metadata, ≤2048 bytes serialized
@@ -219,8 +219,8 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_D
 | `promptContextMaxBytes` | `2048` | Auto-injected `## Live managed processes` block cap. |
 | `requireGitWorkdir` | `true` | Reject specs whose `cwd` isn't a git worktree. |
 | `executableAllowlist` | `[node, bun, npm, …]` | Single global. Applies to `spec.cmd` AND `command` healthcheck `cmd`. |
-| `envKeyAllowlist` | `[NODE_ENV, PORT, …]` | Exact-match env keys. |
-| `envKeyAllowlistPrefixes` | `[VITE_, NEXT_, …]` | Prefix-match env keys. |
+| `envKeyDenyPatterns` | `[^AWS_, ^AZURE_, _SECRET, _TOKEN, _API_KEY, …]` | Regex source strings, matched case-insensitively. Keys matching ANY pattern are rejected unless exact-listed in `envKeyDenyOverrides`. Threat model: credential leakage, not env-key enumeration — plain project vars (`CONSTELLATION_SERVER`, `DATABASE_URL`, …) pass with no config. |
+| `envKeyDenyOverrides` | `[AWS_REGION, AWS_DEFAULT_REGION, AZURE_REGION, GCP_REGION, AWS_PROFILE]` | Exact-match exemptions for known-safe keys that would otherwise be caught by a broad prefix pattern. Case-sensitive. |
 
 ## Failure modes
 

package/engine/managed-spawn.js

@@ -64,15 +64,78 @@ function _isOnAllowlist(name, allowlist) {
   return false;
 }
 
-function _envKeyAllowed(key, limits) {
-  if (typeof key !== 'string' || key.length === 0) return false;
-  const allowlist = Array.isArray(limits.envKeyAllowlist) ? limits.envKeyAllowlist : [];
-  if (allowlist.indexOf(key) >= 0) return true;
-  const prefixes = Array.isArray(limits.envKeyAllowlistPrefixes) ? limits.envKeyAllowlistPrefixes : [];
-  for (const p of prefixes) {
-    if (typeof p === 'string' && p.length > 0 && key.indexOf(p) === 0) return true;
+// Env-key shape guard. Bash/POSIX-style identifier: leading letter or
+// underscore, followed by letters / digits / underscores. Rejects keys with
+// shell metachars ('FOO;BAR', 'FOO BAR', '$FOO') regardless of deny rules —
+// argv smuggling protection, separate from the credential-shape threat
+// model below.
+const _ENV_KEY_SHAPE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Compile envKeyDenyPatterns once per validator invocation and cache. The
+// returned object also carries the override Set for fast exact-match lookup.
+// All patterns are compiled case-insensitively so '_secret' / '_SECRET' are
+// equivalent; overrides remain case-sensitive (exact match).
+function _compileDenyRules(limits, projectExtraPatterns) {
+  const globalPatterns = Array.isArray(limits.envKeyDenyPatterns) ? limits.envKeyDenyPatterns : [];
+  const extra = Array.isArray(projectExtraPatterns) ? projectExtraPatterns : [];
+  const overridesArr = Array.isArray(limits.envKeyDenyOverrides) ? limits.envKeyDenyOverrides : [];
+  const sources = [];
+  const compiled = [];
+  for (const src of globalPatterns.concat(extra)) {
+    if (typeof src !== 'string' || src.length === 0) continue;
+    let re;
+    try { re = new RegExp(src, 'i'); }
+    catch (_e) { continue; }
+    sources.push(src);
+    compiled.push(re);
   }
-  return false;
+  const overrides = new Set();
+  for (const k of overridesArr) {
+    if (typeof k === 'string' && k.length > 0) overrides.add(k);
+  }
+  return { sources, compiled, overrides };
+}
+
+// Check an env key against compiled deny rules. Returns
+// { allowed: true } when the key passes, or
+// { allowed: false, reason: 'env-key-denied (matched pattern X)' }
+// when blocked. Does NOT enforce the shape guard — callers do that
+// separately so shape-failures get a distinct reason.
+function _envKeyAllowed(key, denyRules) {
+  if (typeof key !== 'string' || key.length === 0) {
+    return { allowed: false, reason: 'env-key-empty' };
+  }
+  if (denyRules.overrides.has(key)) return { allowed: true };
+  for (let i = 0; i < denyRules.compiled.length; i++) {
+    if (denyRules.compiled[i].test(key)) {
+      return { allowed: false, reason: 'env-key-denied (matched pattern ' + denyRules.sources[i] + ')' };
+    }
+  }
+  return { allowed: true };
+}
+
+// Find the configured project whose `localPath` contains the spec's cwd.
+// Returns the most-specific match (longest matching localPath) so nested
+// project layouts (e.g. /repos/parent and /repos/parent/sub) prefer the
+// inner one. Returns null when no project matches or when inputs are
+// missing. Pure — does not touch disk.
+function _resolveProjectForCwd(cwd, projects) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return null;
+  if (!Array.isArray(projects) || projects.length === 0) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const p of projects) {
+    if (!p || typeof p !== 'object') continue;
+    const lp = typeof p.localPath === 'string' ? p.localPath : '';
+    if (!lp) continue;
+    if (!shared.isPathInsideOrEqual(cwd, lp)) continue;
+    const len = path.resolve(lp).length;
+    if (len > bestLen) {
+      best = p;
+      bestLen = len;
+    }
+  }
+  return best;
 }
 
 // Extract the first executable-like token from a shell-style healthcheck cmd
@@ -229,7 +292,16 @@ function _validateSpec(spec, index, limits, opts) {
     }
   }
 
-  // env (optional)
+  // env (optional). Validation has three independent layers:
+  //   1. Shape guard: key matches /^[A-Za-z_][A-Za-z0-9_]*$/ (argv-smuggling
+  //      protection). Reason: env-key-invalid-shape.
+  //   2. Denylist: key does NOT match any credential-shaped pattern unless
+  //      explicitly listed in envKeyDenyOverrides. Per-project tightening
+  //      (project.managedSpawnExtraDenyPatterns) can add MORE patterns
+  //      when spec.cwd resolves under that project's localPath — projects
+  //      can only tighten, never loosen (asymmetric on purpose; no
+  //      per-project override list).
+  //   3. Value sanity: string, ≤1000 chars.
   const envRaw = spec.env == null ? {} : spec.env;
   if (typeof envRaw !== 'object' || Array.isArray(envRaw)) {
     return { ok: false, reason: 'env-not-object' };
@@ -239,10 +311,22 @@ function _validateSpec(spec, index, limits, opts) {
   if (envKeys.length > maxEnv) {
     return { ok: false, reason: 'env-too-many (>' + maxEnv + ')' };
   }
+  const projectForSpec = _resolveProjectForCwd(
+    typeof spec.cwd === 'string' ? spec.cwd : '',
+    opts && Array.isArray(opts.projects) ? opts.projects : null,
+  );
+  const projectExtraPatterns = projectForSpec && Array.isArray(projectForSpec.managedSpawnExtraDenyPatterns)
+    ? projectForSpec.managedSpawnExtraDenyPatterns
+    : null;
+  const denyRules = _compileDenyRules(limits, projectExtraPatterns);
   const env = {};
   for (const k of envKeys) {
-    if (!_envKeyAllowed(k, limits)) {
-      return { ok: false, reason: 'env-key-not-on-allowlist (' + k + ')' };
+    if (!_ENV_KEY_SHAPE_RE.test(k)) {
+      return { ok: false, reason: 'env-key-invalid-shape (' + k + ')' };
+    }
+    const decision = _envKeyAllowed(k, denyRules);
+    if (!decision.allowed) {
+      return { ok: false, reason: decision.reason };
     }
     const v = envRaw[k];
     if (typeof v !== 'string') return { ok: false, reason: 'env-value-not-string (' + k + ')' };
@@ -323,10 +407,25 @@ function validateManagedSpawnRecord(parsed, opts) {
     return { ok: false, reason: 'specs-too-many (>' + maxSpecs + ')' };
   }
 
+  // Resolve `projects` for per-project env-deny tightening. Callers (tests,
+  // future engine wiring) may pre-supply `opts.projects` for determinism;
+  // when undefined we lazy-load from MINIONS_DIR/config.json so the engine
+  // close-handler doesn't have to change signature. A read failure or a
+  // config without `projects` falls back to `[]` — unchanged behavior, the
+  // global deny patterns remain the only source.
+  let projects;
+  if (Array.isArray(opts.projects)) {
+    projects = opts.projects;
+  } else {
+    try { projects = shared.getProjects(); }
+    catch (_e) { projects = []; }
+  }
+  const specOpts = Object.assign({}, opts, { projects: projects });
+
   const seen = new Set();
   const out = [];
   for (let i = 0; i < parsed.specs.length; i++) {
-    const v = _validateSpec(parsed.specs[i], i, limits, opts);
+    const v = _validateSpec(parsed.specs[i], i, limits, specOpts);
     if (!v.ok) {
       // Preserve workdir-rejection prefix at the top level so the engine
       // close-handler gate can key off it the same way it does for
@@ -489,7 +588,7 @@ function buildManagedSpawnHint(opts) {
     '- Specs per file: ≤ ' + maxSpecs,
     '- Name: kebab-case, ≤ 64 chars, unique within file',
     '- Executable (`cmd` and any `command` healthcheck cmd): on the engine\'s allowlist (node, bun, npm, npx, python, docker, adb, gradle, mvn, pwsh, …)',
-    '- Env keys: on the engine\'s allowlist or matching a known prefix (e.g. `VITE_`, `NEXT_`, `REACT_APP_`, `npm_config_`)',
+    '- Env keys: any well-formed POSIX identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`) is accepted EXCEPT keys matching credential-shaped deny patterns (`*_SECRET`, `*_TOKEN`, `*_API_KEY`, `*_PASSWORD`, `*_PRIVATE_KEY`, `*_CREDENTIALS`, `*_AUTH`, `*_PAT`, `AWS_*`, `AZURE_*`, `GCP_*`, `GH_TOKEN`, `GITHUB_TOKEN`, `OPENAI_*`, `ANTHROPIC_*`, `COPILOT_*`, `DOCKER_AUTH*`, `NPM_TOKEN`). Region/profile names (`AWS_REGION`, `AWS_PROFILE`, …) are exempt. If your service genuinely needs a credential-looking var, rename it (e.g. `DATABASE_URL` not `DB_API_KEY`) or stash the value in `attrs` and have the child read it from there. **The engine forwards env values verbatim — the deny shape is a tripwire, not a scrubber. Do not put real credentials in env even if the key passes.** Projects may tighten by adding patterns to `config.projects[N].managedSpawnExtraDenyPatterns`; projects cannot loosen.',
     '- Ports: 1024–65535, ≤ 20 per spec',
     '- TTL: ≤ ' + maxTtl + ' minutes (hard cap), defaults to ' + defaultTtl + ' if omitted',
     '- `attrs` serialized: ≤ 2048 bytes (opaque blob the engine surfaces to downstream agents)',

package/engine/shared.js

@@ -1526,24 +1526,36 @@ const ENGINE_DEFAULTS = {
       'curl', 'wget',
       'git',
     ],
-    // Env-key allowlist (exact match). Tight by default so a managed spec
-    // can't leak credentials (AWS_*, AZURE_*, GH_TOKEN, etc.). Anything not
-    // here must match one of the allowed prefixes below.
-    envKeyAllowlist: [
-      'NODE_ENV', 'PORT', 'HOST', 'PATH',
-      'DEBUG', 'LOG_LEVEL',
-      'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP',
-      'LANG', 'LC_ALL',
-      'JAVA_HOME', 'ANDROID_HOME', 'ANDROID_SDK_ROOT',
+    // Env-key denylist (regex source strings, matched case-insensitively).
+    // The threat model is credential leakage, not env-key enumeration —
+    // any key NOT matching one of these patterns is accepted, so project
+    // vars like CONSTELLATION_SERVER / DATABASE_URL / REDIS_HOST work with
+    // zero engine config. Patterns are compiled lazily by the validator
+    // and tested in order; the first match wins for the reject reason, so
+    // the more specific prefix patterns are listed before the broad
+    // suffix patterns (a key like AWS_SECRET_ACCESS_KEY should report the
+    // narrower `^AWS_` cause, not the generic `_SECRET` cause). Extend
+    // with caution; broad patterns belong here, ecosystem allow
+    // exemptions belong in `envKeyDenyOverrides`.
+    envKeyDenyPatterns: [
+      // Prefix patterns first (more specific cause for vendor keys).
+      '^AWS_', '^AZURE_', '^GCP_', '^GOOGLE_APPLICATION_CREDENTIALS',
+      '^GH_TOKEN', '^GITHUB_TOKEN',
+      '^OPENAI_', '^ANTHROPIC_', '^COPILOT_',
+      '^DOCKER_AUTH', '^NPM_TOKEN',
+      // Suffix / substring patterns (generic credential shapes).
+      '_SECRET', '_TOKEN', '_API_KEY', '_APIKEY',
+      '_PASSWORD', '_PASSWD',
+      '_PRIVATE_KEY', '_PRIVKEY',
+      '_CREDENTIALS', '_AUTH', '_PAT',
     ],
-    // Env-key prefix allowlist. Standard ecosystem prefixes that frontends
-    // and tooling depend on (Vite, Next.js, CRA, npm scripts). Extend with
-    // caution; broad prefixes (`AWS_`, `AZURE_`) belong on a deny-list, not
-    // an allow-list.
-    envKeyAllowlistPrefixes: [
-      'VITE_', 'NEXT_', 'REACT_APP_', 'NUXT_', 'GATSBY_',
-      'npm_config_', 'NPM_CONFIG_',
-      'MINIONS_',
+    // Exact-match exemption list for keys that would otherwise be caught
+    // by a broad deny pattern (region/profile names aren't secrets).
+    // Match is case-sensitive — the override key must equal the spec key
+    // exactly.
+    envKeyDenyOverrides: [
+      'AWS_REGION', 'AWS_DEFAULT_REGION', 'AZURE_REGION', 'GCP_REGION',
+      'AWS_PROFILE',
     ],
   },
   // Backward-compat: keep `engine.claude.*` field family deprecation tracker. Listed here so preflight

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1976",
+  "version": "0.1.1978",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"