flecto 3.0.1 → 3.0.2

package/src/encrypted.js

@@ -292,14 +292,14 @@ function mapStrings(value, mapString) {
 
   if (isPlainObject(value)) {
     let changed = false;
-    /** @type {Record<string, unknown>} */
-    const out = {};
-    for (const [key, item] of Object.entries(value)) {
+    // Rebuilt with fromEntries, not `out[key] = next`: a key literally named
+    // "__proto__" would run the prototype setter and drop the subtree.
+    const entries = Object.entries(value).map(([key, item]) => {
       const next = mapStrings(item, mapString);
       if (next !== item) changed = true;
-      out[key] = next;
-    }
-    return changed ? out : value;
+      return [key, next];
+    });
+    return changed ? Object.fromEntries(entries) : value;
   }
 
   return value;
@@ -385,14 +385,12 @@ function normalizeRecipientGroup(group, value) {
  */
 function normalizeSopsBlock(block) {
   let changed = false;
-  /** @type {Record<string, unknown>} */
-  const out = {};
-  for (const [key, value] of Object.entries(block)) {
+  const entries = Object.entries(block).map(([key, value]) => {
     const next = RECIPIENT_GROUPS.includes(key) ? normalizeRecipientGroup(key, value) : value;
     if (next !== value) changed = true;
-    out[key] = next;
-  }
-  return changed ? out : block;
+    return [key, next];
+  });
+  return changed ? Object.fromEntries(entries) : block;
 }
 
 /**
@@ -436,7 +434,12 @@ export function normalizeEncrypted(tree, documentKeys = []) {
     const normalized = normalizeSopsOwner(doc);
     if (normalized === doc) continue;
     if (out === redacted) out = { ...redacted };
-    out[key] = normalized;
+    Object.defineProperty(out, key, {
+      value: normalized,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
   }
   return out;
 }

package/src/packs/github-actions.json

@@ -0,0 +1,92 @@
+{
+  "id": "github-actions",
+  "expandSubtrees": true,
+  "rules": [
+    {
+      "id": "github-actions-pull-request-target",
+      "severity": "error",
+      "when": ["added"],
+      "match": { "pathEquals": "on.pull_request_target" },
+      "message": "A pull_request_target trigger was added. Do not run fork-controlled code in a privileged workflow; separate metadata checks from untrusted execution."
+    },
+    {
+      "id": "github-actions-permissions-removed",
+      "severity": "error",
+      "when": ["removed"],
+      "match": { "pathEquals": "permissions" },
+      "message": "The workflow permissions block was removed. GitHub may restore a broader default token scope; keep an explicit least-privilege block."
+    },
+    {
+      "id": "github-actions-permissions-write-all",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "pathEquals": "permissions" },
+      "afterEquals": "write-all",
+      "message": "The workflow token was widened to write-all. Scope permissions to the specific resources and operations required by the job."
+    },
+    {
+      "id": "github-actions-permission-write-scope",
+      "severity": "warn",
+      "when": ["added", "changed"],
+      "match": { "path": "^permissions\\.[^.]+$" },
+      "afterEquals": "write",
+      "messageTemplate": "Workflow permission {path} was widened to write. Confirm the job and its trigger need write access."
+    },
+    {
+      "id": "github-actions-unpinned-action",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.uses$" },
+      "afterMatches": "^.+@(?![0-9a-fA-F]{40}$).+$",
+      "messageTemplate": "Action {after} is not pinned to a full commit SHA at {path}. Pin third-party actions to an immutable SHA and keep the release in a comment."
+    },
+    {
+      "id": "github-actions-pull-request-head-checkout",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.with\\.ref$" },
+      "afterMatches": "^(?:github\\.event\\.pull_request\\.head\\.sha|\\$\\{\\{\\s*github\\.event\\.pull_request\\.head\\.sha\\s*\\}\\})$",
+      "message": "The workflow checks out the pull request head SHA. Recheck the trust boundary before combining this with pull_request_target or write permissions."
+    },
+    {
+      "id": "github-actions-secrets-in-run",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.steps\\[[0-9]+\\]\\.run$" },
+      "afterMatches": "\\$\\{\\{\\s*secrets\\.[^}]+\\}\\}",
+      "message": "A GitHub secret is interpolated into a run step. Prefer an environment boundary and ensure untrusted pull-request code cannot reach the step."
+    },
+    {
+      "id": "github-actions-self-hosted-runner",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": { "path": "^jobs\\.[^.]+\\.runs-on(?:\\.labels)?(?:\\[[0-9]+\\])?$" },
+      "anyOf": [
+        { "afterMatches": "(^|[ ,])self-hosted([ ,]|$)" },
+        { "afterAnyMatches": "(^|[ ,])self-hosted([ ,]|$)" }
+      ],
+      "message": "A self-hosted runner is reachable from this workflow. Confirm that fork-controlled changes cannot execute on a runner with persistent credentials."
+    },
+    {
+      "id": "github-actions-schedule-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.schedule" },
+      "message": "A scheduled trigger was added. Review which jobs and secrets become reachable without a pull request review."
+    },
+    {
+      "id": "github-actions-workflow-dispatch-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.workflow_dispatch" },
+      "message": "A manual workflow trigger was added. Document who may run it and which permissions or secrets it can reach."
+    },
+    {
+      "id": "github-actions-workflow-call-exposed",
+      "severity": "warn",
+      "when": ["added"],
+      "match": { "pathEquals": "on.workflow_call" },
+      "message": "A reusable workflow trigger was added. Review its caller permissions and secret inheritance before treating it as a trusted boundary."
+    }
+  ]
+}

package/src/parser.js

@@ -5,8 +5,14 @@ import TOML from '@iarna/toml';
 import dotenv from 'dotenv';
 import { isArmoredAgeFile, normalizeEncrypted, opaqueFileState } from './encrypted.js';
 import { documentKeysOf, withDocumentKeys } from './documents.js';
+import { assertNotTerraformPlan } from './terraform.js';
 
-const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
+const SUPPORTED_EXT = ['.json', '.jsonc', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
+
+// Upper bound on nodes produced when normalizing a parsed tree. Well above any
+// real config (a 5,000-key file is 5,000 nodes) and below where alias expansion
+// becomes a denial of service. See normalizeParsedValue.
+const MAX_NORMALIZED_NODES = 5_000_000;
 
 /**
  * True for dotenv-like names: `.env`, `.env.*`, `*.env`
@@ -25,24 +31,63 @@ export function isIniFilename(filepath) {
   return extname(filepath).toLowerCase() === '.ini';
 }
 
+/**
+ * Define an own data property, whatever the key is called.
+ *
+ * `target[key] = value` is not a property write when `key` is `"__proto__"`: it
+ * runs the `Object.prototype.__proto__` setter instead, which either reassigns
+ * the object's prototype or silently discards the value. `defineProperty` is the
+ * operation that was actually meant every time a parser writes a key it read out
+ * of a file, and it treats every key name the same.
+ * @param {Record<string, unknown>} target
+ * @param {string} key
+ * @param {unknown} value
+ */
+function defineOwn(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 /**
  * Minimal INI parser: [section] + key=value.
  * Root keys are top-level; sectioned keys nest under the section name.
+ *
+ * Section and key names come out of the file, which in Flecto's threat model
+ * means they come out of a pull request. They are read and written as **own
+ * properties only**: `out[section]` on a section named `__proto__` resolves to
+ * `Object.prototype` — which passes `isPlainObject`, since its own prototype is
+ * `null` — and every key in that section would then be written onto the
+ * prototype of every object in the process. `Object.hasOwn` for the lookup and
+ * `defineOwn` for the write make a reserved name an ordinary key holding
+ * ordinary data, which is what a config file's `[__proto__]` section is.
  * @param {string} raw
  * @returns {Record<string, unknown>}
  */
 export function parseIni(raw) {
   /** @type {Record<string, unknown>} */
   const out = {};
-  let section = null;
+  /** @type {Record<string, unknown>} */
+  let bucket = out;
 
   for (const line of String(raw).split(/\r?\n/)) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith(';') || trimmed.startsWith('#')) continue;
     const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
     if (sectionMatch) {
-      section = sectionMatch[1].trim();
-      if (!isPlainObject(out[section])) out[section] = {};
+      const section = sectionMatch[1].trim();
+      const existing = Object.hasOwn(out, section) ? out[section] : undefined;
+      if (isPlainObject(existing)) {
+        bucket = /** @type {Record<string, unknown>} */ (existing);
+      } else {
+        // A repeated section keeps accumulating; a section colliding with a
+        // root scalar replaces it, exactly as before.
+        bucket = {};
+        defineOwn(out, section, bucket);
+      }
       continue;
     }
     const eq = trimmed.indexOf('=');
@@ -55,17 +100,106 @@ export function parseIni(raw) {
     ) {
       value = value.slice(1, -1);
     }
-    if (section == null) {
-      out[key] = value;
-    } else {
-      /** @type {Record<string, string>} */
-      const bucket = /** @type {any} */ (out[section]);
-      bucket[key] = value;
-    }
+    defineOwn(bucket, key, value);
   }
   return out;
 }
 
+/**
+ * Parse JSON that may carry line and block comments and trailing commas —
+ * the JSONC dialect `tsconfig.json`, `.vscode/settings.json`, `jsconfig.json`,
+ * and `devcontainer.json` are written in by convention.
+ *
+ * Comments are blanked rather than removed: every stripped character is
+ * replaced by a space, and newlines inside a block comment are kept as
+ * newlines. That keeps byte offsets and line/column numbers identical to the
+ * original file, so the position `JSON.parse` reports on a real syntax error
+ * still points at the line the author has open. Deleting the spans instead
+ * would silently shift every error after the first comment.
+ *
+ * The scan tracks string state, because the naive strip is wrong on exactly
+ * the values config files are full of: `"https://example.com"` contains `//`,
+ * and a `/*` may sit inside a string just as legitimately. Backslash escapes
+ * are consumed as a pair so a `\"` never looks like the end of a string.
+ *
+ * Note that comments are not preserved on the parsed value. Flecto only ever
+ * reads config, so nothing is written back — but a snapshot records the parsed
+ * structure, not the file, and comments are not part of it.
+ * @param {string} raw
+ * @returns {unknown}
+ */
+export function parseJsonc(raw) {
+  return JSON.parse(stripJsonComments(raw));
+}
+
+/**
+ * Blank out JSONC comments and trailing commas, preserving every byte offset.
+ * Exported for tests; {@link parseJsonc} is the parsing entry point.
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripJsonComments(raw) {
+  const text = String(raw);
+  const out = text.split('');
+  const blank = (from, to) => {
+    for (let k = from; k < to; k += 1) {
+      // Keep line breaks so line numbers in parse errors stay true.
+      if (out[k] !== '\n' && out[k] !== '\r') out[k] = ' ';
+    }
+  };
+
+  // Index of a comma that has seen nothing but whitespace since, or -1. When a
+  // closing brace or bracket arrives it is a trailing comma and gets blanked.
+  let pendingComma = -1;
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i];
+
+    if (ch === '"') {
+      // A string is opaque: scan to its unescaped closing quote.
+      pendingComma = -1;
+      i += 1;
+      while (i < text.length) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === '"') { i += 1; break; }
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === '/' && text[i + 1] === '/') {
+      let end = i + 2;
+      while (end < text.length && text[end] !== '\n' && text[end] !== '\r') end += 1;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (ch === '/' && text[i + 1] === '*') {
+      const closed = text.indexOf('*/', i + 2);
+      // An unterminated block comment runs to end of input. Blanking it leaves
+      // JSON.parse to report the truncated document, which is the real error.
+      const end = closed === -1 ? text.length : closed + 2;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (ch === ',') {
+      pendingComma = i;
+    } else if (ch === '}' || ch === ']') {
+      if (pendingComma !== -1) out[pendingComma] = ' ';
+      pendingComma = -1;
+    } else if (ch !== ' ' && ch !== '\t' && ch !== '\n' && ch !== '\r') {
+      pendingComma = -1;
+    }
+    i += 1;
+  }
+
+  return out.join('');
+}
+
 function isPlainObject(v) {
   if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
   const prototype = Object.getPrototypeOf(v);
@@ -98,18 +232,34 @@ export const CIRCULAR_SENTINEL = '<circular>';
  * rather than e.g. a back-reference path, so two files with the same cycle
  * shape normalize to the same tree and compare equal — the whole point of a
  * stable, readable diff path.
+ *
+ * A budget bounds the total nodes produced. YAML aliases resolve to shared
+ * object *references*, so a tiny file — `a: &a [x,…]`, `b: [*a,*a,…]`, repeated
+ * a handful of levels — parses to a small DAG that this function expands into an
+ * exponentially large *tree* (each alias reference is normalized independently,
+ * on purpose, so two files with the same shape compare equal). Without a bound,
+ * a few hundred bytes of nested aliases hang the process — a "billion laughs"
+ * denial of service reachable on any parsed file. The budget makes it fail with
+ * a clear error instead. The limit is far above any real config.
  * @param {unknown} value
  * @param {Set<object>} [ancestors] internal recursion state; omit when calling
+ * @param {{ n: number }} [budget] internal node counter; omit when calling
  * @returns {unknown}
  */
-function normalizeParsedValue(value, ancestors = new Set()) {
+function normalizeParsedValue(value, ancestors = new Set(), budget = { n: 0 }) {
+  if (++budget.n > MAX_NORMALIZED_NODES) {
+    throw new Error(
+      `document expands to too many nodes (limit ${MAX_NORMALIZED_NODES}); `
+      + 'this is usually YAML alias expansion (a "billion laughs" bomb)',
+    );
+  }
   if (typeof value === 'bigint') return String(value);
   if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
   if (value instanceof Date) return value.toJSON();
   if (Array.isArray(value)) {
     if (ancestors.has(value)) return CIRCULAR_SENTINEL;
     ancestors.add(value);
-    const out = value.map((item) => normalizeParsedValue(item, ancestors));
+    const out = value.map((item) => normalizeParsedValue(item, ancestors, budget));
     ancestors.delete(value);
     return out;
   }
@@ -120,14 +270,14 @@ function normalizeParsedValue(value, ancestors = new Set()) {
   ) {
     const serialized = value.toJSON();
     if (serialized !== value && (serialized === null || typeof serialized !== 'object')) {
-      return normalizeParsedValue(serialized, ancestors);
+      return normalizeParsedValue(serialized, ancestors, budget);
     }
   }
   if (isPlainObject(value)) {
     if (ancestors.has(value)) return CIRCULAR_SENTINEL;
     ancestors.add(value);
     const out = Object.fromEntries(
-      Object.entries(value).map(([key, child]) => [key, normalizeParsedValue(child, ancestors)]),
+      Object.entries(value).map(([key, child]) => [key, normalizeParsedValue(child, ancestors, budget)]),
     );
     ancestors.delete(value);
     return out;
@@ -170,6 +320,25 @@ function documentIdentity(doc) {
   return scalarField(doc, 'id') ?? scalarField(doc, 'name');
 }
 
+/**
+ * True for a document that carries the Kubernetes resource markers `apiVersion`
+ * and `kind`. This is the signal used to decide whether a *single*-document file
+ * should be keyed by identity like a multi-document one (#124): a manifest that
+ * gains a second document beside it must keep the paths it had, and the only way
+ * to do that is to key it the same way whether it stands alone or not.
+ *
+ * Ordinary config that happens to have a `kind` but no `apiVersion` — a form
+ * field, say — is not treated as a manifest, so single-document config files are
+ * untouched.
+ * @param {unknown} doc
+ * @returns {boolean}
+ */
+function isKubernetesDocument(doc) {
+  return isPlainObject(doc)
+    && scalarField(doc, 'apiVersion') !== null
+    && scalarField(doc, 'kind') !== null;
+}
+
 /**
  * Keys for a multi-document file: identities when every document has a unique
  * one, otherwise document indices. It is all-or-nothing so keys within one file
@@ -194,10 +363,12 @@ function documentKeys(docs) {
 /**
  * Parse a YAML stream, supporting `---`-separated multi-document files.
  *
- * A file holding a single document parses to that document unchanged, so diff
- * paths for ordinary YAML are untouched. A file holding several documents
- * parses to an object keyed per document, which lets the differ walk it like
- * any other tree. Empty documents (a leading or trailing `---`, or a `null`
+ * A file holding a single *non-manifest* document parses to that document
+ * unchanged, so diff paths for ordinary YAML are untouched. A file holding
+ * several documents — or a single Kubernetes manifest — parses to an object
+ * keyed per document, which lets the differ walk it like any other tree and,
+ * crucially, keeps a manifest's paths stable when a second document is added
+ * beside it (#124). Empty documents (a leading or trailing `---`, or a `null`
  * document) are dropped, so a stray separator does not create a phantom entry.
  *
  * The keys it invents are recorded on the wrapper (see documents.js) so that
@@ -211,7 +382,20 @@ export function parseYamlStream(raw) {
   const docs = yaml.loadAll(raw).filter((doc) => doc != null);
 
   if (docs.length === 0) return withDocumentKeys({}, []);
-  if (docs.length === 1) return withDocumentKeys(docs[0], []);
+
+  // A lone document is normally returned bare, preserving ordinary YAML paths.
+  // The exception is a Kubernetes manifest with a resolvable identity: keying it
+  // now means adding a second document later leaves its paths unchanged, instead
+  // of re-pathing the whole file and reporting the untouched resource as
+  // removed-and-re-added. Ordinary single-document config is unaffected.
+  if (docs.length === 1) {
+    const [doc] = docs;
+    const identity = isKubernetesDocument(doc) ? documentIdentity(doc) : null;
+    if (identity == null || identity === '__proto__') {
+      return withDocumentKeys(doc, []);
+    }
+    return withDocumentKeys({ [identity]: doc }, [identity]);
+  }
 
   const keys = documentKeys(docs);
   /** @type {Record<string, unknown>} */
@@ -267,8 +451,8 @@ export function parseContent(filepath, raw) {
       parsed = dotenv.parse(raw);
     } else if (iniLike) {
       parsed = parseIni(raw);
-    } else if (ext === '.json') {
-      parsed = JSON.parse(raw);
+    } else if (ext === '.json' || ext === '.jsonc') {
+      parsed = parseJsonc(raw);
     } else if (ext === '.yaml' || ext === '.yml') {
       parsed = parseYamlStream(raw);
     } else if (ext === '.toml') {
@@ -282,6 +466,12 @@ export function parseContent(filepath, raw) {
     );
   }
 
+  // Guarded here, on the one path every generic command shares, rather than in
+  // each command: ci, watch, compare, report, and snapshot reads all land here,
+  // and so does a plan read out of git via --snapshot-ref. `flecto plan` reads
+  // through readTerraformPlanFile() instead and is unaffected (#113).
+  assertNotTerraformPlan(parsed, filepath);
+
   const keys = documentKeysOf(parsed) ?? [];
   return withDocumentKeys(normalizeEncrypted(normalizeParsedValue(parsed), keys), keys);
 }

package/src/policy-test.js

@@ -90,7 +90,7 @@ export function assertExpectedFindings(actual, expected) {
 /**
  * Run a policy fixture stored in a directory.
  * @param {string} fixtureDir
- * @param {{ configName?: string }} [options]
+ * @param {{ configName?: string, cwd?: string }} [options]
  */
 export async function testPolicyFixture(fixtureDir, options = {}) {
   const dir = resolve(fixtureDir);
@@ -117,6 +117,10 @@ export async function testPolicyFixture(fixtureDir, options = {}) {
     source: config.source ?? 'ci',
     policies: config.policies,
     plugins: config.plugins,
+    // A fixture's own policies/ still wins, so self-contained fixtures behave
+    // exactly as before. The invoking project is a fallback, which is where
+    // `flecto policies add` installs packs (#114).
+    packRoots: [options.cwd ?? process.cwd()],
   });
   assertExpectedFindings(findings, config.expected);