flecto 2.1.0 → 3.0.0

package/src/packs/terraform.json

@@ -0,0 +1,120 @@
+{
+  "id": "terraform",
+  "rules": [
+    {
+      "id": "terraform-resource-replaced",
+      "severity": "error",
+      "when": ["removed"],
+      "match": {
+        "path": "\\.#action$"
+      },
+      "beforeEquals": "replace",
+      "message": "Terraform will destroy and recreate this resource. Expect downtime, a new resource id, and the loss of anything held only on the existing instance. Check which attribute forced the replacement."
+    },
+    {
+      "id": "terraform-stateful-resource-destroyed",
+      "severity": "error",
+      "when": ["removed"],
+      "match": {
+        "path": "(^|\\.)(aws_db_instance|aws_db_cluster_snapshot|aws_rds_cluster|aws_rds_cluster_instance|aws_dynamodb_table|aws_s3_bucket|aws_ebs_volume|aws_efs_file_system|aws_elasticache_cluster|aws_elasticache_replication_group|aws_redshift_cluster|aws_docdb_cluster|aws_neptune_cluster|google_sql_database_instance|google_storage_bucket|azurerm_storage_account|azurerm_mssql_database)\\..*\\.#action$"
+      },
+      "beforeIn": ["delete", "replace"],
+      "message": "Terraform will destroy a stateful resource. Its data does not survive. Take a final snapshot, or add a prevent_destroy lifecycle block, before applying."
+    },
+    {
+      "id": "terraform-security-group-open-ingress",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "afterIn": ["0.0.0.0/0", "::/0"],
+      "anyOf": [
+        {
+          "match": {
+            "path": "(^|\\.)aws_security_group\\..*\\.ingress\\[[^\\]]*\\]\\.(ipv6_)?cidr_blocks\\[[^\\]]*\\]$"
+          }
+        },
+        {
+          "match": {
+            "path": "(^|\\.)aws_vpc_security_group_ingress_rule\\..*\\.cidr_ipv[46]$"
+          }
+        }
+      ],
+      "messageTemplate": "Security group ingress will accept traffic from the whole internet ({after}). Restrict the source to a known CIDR, a prefix list, or another security group."
+    },
+    {
+      "id": "terraform-iam-wildcard",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)aws_iam_[a-z_]+\\..*\\.policy$"
+      },
+      "afterMatches": "\"(Action|NotAction|Resource|NotResource)\"\\s*:\\s*(\"\\*\"|\\[[^\\]]*\"\\*\")",
+      "message": "IAM policy grants a wildcard action or resource (\"*\"). Scope it to the specific actions and ARNs the principal needs."
+    },
+    {
+      "id": "terraform-s3-public-access-block-disabled",
+      "severity": "error",
+      "when": ["added", "changed", "removed"],
+      "anyOf": [
+        {
+          "match": {
+            "path": "(^|\\.)aws_s3_bucket_public_access_block\\..*\\.(block_public_acls|block_public_policy|ignore_public_acls|restrict_public_buckets)$"
+          },
+          "afterEquals": false
+        },
+        {
+          "match": {
+            "path": "(^|\\.)aws_s3_bucket_public_access_block\\..*\\.#action$"
+          },
+          "beforeIn": ["delete", "replace"]
+        }
+      ],
+      "message": "S3 public access block is being turned off or removed. Leave all four block_public_* settings enabled unless the bucket is deliberately a public website."
+    },
+    {
+      "id": "terraform-s3-public-acl",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)aws_s3_bucket(_acl)?\\..*\\.acl$"
+      },
+      "afterIn": ["public-read", "public-read-write", "authenticated-read"],
+      "messageTemplate": "S3 bucket ACL set to \"{after}\", which exposes objects outside the account. Use a bucket policy scoped to known principals instead."
+    },
+    {
+      "id": "terraform-instance-size-changed",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": {
+        "path": "(^|\\.)(aws_instance|aws_db_instance|aws_rds_cluster_instance|aws_launch_template|aws_launch_configuration|aws_elasticache_cluster|google_compute_instance|azurerm_linux_virtual_machine|azurerm_windows_virtual_machine)\\..*\\.(instance_type|instance_class|node_type|machine_type|size|vm_size)$"
+      },
+      "messageTemplate": "Instance size changes from {before} to {after}. Confirm the cost impact, and whether the change forces a restart or a replacement."
+    },
+    {
+      "id": "terraform-capacity-jump",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": {
+        "path": "\\.(desired_capacity|max_size|min_size|desired_count|node_count|initial_node_count|instance_count|number_of_nodes|max_capacity|min_capacity)$"
+      },
+      "numericJump": { "minMultiple": 2 },
+      "messageTemplate": "Capacity at {path} jumps from {before} to {after} (>=2x). Confirm the quota headroom and the cost of the new floor."
+    },
+    {
+      "id": "terraform-sensitive-value-changed",
+      "severity": "warn",
+      "when": ["added", "changed", "removed"],
+      "anyOf": [
+        { "afterEquals": "(sensitive value)" },
+        { "beforeEquals": "(sensitive value)" }
+      ],
+      "message": "A value Terraform marks sensitive is being set, changed, or removed. Flecto redacted it. Confirm it lives in a secret store and that anything depending on it is rotated."
+    },
+    {
+      "id": "terraform-hardcoded-credential",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "afterLooksSecret": true,
+      "message": "A planned attribute value looks like a credential (known token format or high-entropy string) that Terraform did not mark sensitive. Move it to a secret store and rotate it."
+    }
+  ]
+}

package/src/parser.js

@@ -3,8 +3,10 @@ import { basename, extname } from 'path';
 import yaml from 'js-yaml';
 import TOML from '@iarna/toml';
 import dotenv from 'dotenv';
+import { isArmoredAgeFile, normalizeEncrypted, opaqueFileState } from './encrypted.js';
+import { documentKeysOf, withDocumentKeys } from './documents.js';
 
-const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini'];
+const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
 
 /**
  * True for dotenv-like names: `.env`, `.env.*`, `*.env`
@@ -65,11 +67,175 @@ export function parseIni(raw) {
 }
 
 function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const prototype = Object.getPrototypeOf(v);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * What a YAML anchor that points back at one of its own containers collapses
+ * to. See {@link normalizeParsedValue} for why this is necessary and why a
+ * plain sentinel, rather than e.g. a path reference, is enough.
+ */
+export const CIRCULAR_SENTINEL = '<circular>';
+
+/**
+ * Convert parser-specific scalar objects into a stable JSON-safe tree before
+ * they reach snapshots, the differ, or output renderers.
+ *
+ * A recursive YAML anchor (`a: &x\n  b: *x`) parses to a genuinely cyclic
+ * object — js-yaml resolves the alias to the *same* object reference, not a
+ * copy, so `a.b === a`. `ancestors` tracks the containers on the path
+ * currently being walked, the same ancestor-tracking pattern `collectLeaves`
+ * in policy.js uses for the same reason; revisiting one replaces the
+ * back-reference with {@link CIRCULAR_SENTINEL} instead of recursing into it.
+ * A value merely reached twice by separate branches (not an ancestor of
+ * itself) is still normalized in full on each branch.
+ *
+ * The result is always plain JSON: safe for `JSON.stringify` at the snapshot
+ * write, and safe for the differ, which never sees a cycle because nothing
+ * downstream of this function ever does. The sentinel is a fixed string
+ * 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.
+ * @param {unknown} value
+ * @param {Set<object>} [ancestors] internal recursion state; omit when calling
+ * @returns {unknown}
+ */
+function normalizeParsedValue(value, ancestors = new Set()) {
+  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));
+    ancestors.delete(value);
+    return out;
+  }
+  if (
+    value !== null
+    && typeof value === 'object'
+    && typeof value.toJSON === 'function'
+  ) {
+    const serialized = value.toJSON();
+    if (serialized !== value && (serialized === null || typeof serialized !== 'object')) {
+      return normalizeParsedValue(serialized, ancestors);
+    }
+  }
+  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)]),
+    );
+    ancestors.delete(value);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Read a scalar field as a non-empty string, or null.
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @returns {string | null}
+ */
+function scalarField(obj, key) {
+  const value = obj[key];
+  if (value == null || typeof value === 'object') return null;
+  const text = String(value).trim();
+  return text === '' ? null : text;
+}
+
+/**
+ * Stable identity for one document of a multi-document YAML file.
+ * Kubernetes-shaped documents key on `kind/name`, with the namespace inserted
+ * when present (`kind/namespace/name`). Anything else falls back to a top-level
+ * `id` then `name`, mirroring array identity matching in the differ.
+ * @param {unknown} doc
+ * @returns {string | null} null when the document has no stable identity
+ */
+function documentIdentity(doc) {
+  if (!isPlainObject(doc)) return null;
+
+  const kind = scalarField(doc, 'kind');
+  const metadata = isPlainObject(doc.metadata) ? doc.metadata : null;
+  const name = metadata ? scalarField(metadata, 'name') : null;
+  if (kind && name) {
+    const namespace = scalarField(metadata, 'namespace');
+    return namespace ? `${kind}/${namespace}/${name}` : `${kind}/${name}`;
+  }
+
+  return scalarField(doc, 'id') ?? scalarField(doc, 'name');
+}
+
+/**
+ * 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
+ * stay homogeneous.
+ * @param {unknown[]} docs
+ * @returns {string[]}
+ */
+function documentKeys(docs) {
+  const identities = docs.map((doc) => {
+    const identity = documentIdentity(doc);
+    // "__proto__" as a key would mutate the prototype instead of adding an
+    // entry, silently losing the document. Fall back to indices instead.
+    return identity === '__proto__' ? null : identity;
+  });
+  const unique = new Set(identities);
+  if (!identities.includes(null) && unique.size === identities.length) {
+    return /** @type {string[]} */ (identities);
+  }
+  return docs.map((_, index) => String(index));
+}
+
+/**
+ * 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`
+ * 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
+ * everything downstream can tell a synthetic document prefix from a real
+ * configuration key without having to guess from its shape.
+ * @param {string} raw
+ * @returns {unknown}
+ * @throws {Error} on YAML syntax errors
+ */
+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], []);
+
+  const keys = documentKeys(docs);
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (let i = 0; i < docs.length; i++) {
+    out[keys[i]] = docs[i];
+  }
+  return withDocumentKeys(out, keys);
 }
 
 /**
  * Auto-detect the format of a file and parse it into a plain JS object.
+ *
+ * The parsed tree then goes through the encryption pass (see encrypted.js),
+ * which replaces every ciphertext-bearing value with an opaque sentinel. Doing
+ * it here rather than at render time is what makes the guarantee absolute:
+ * nothing downstream — diff, snapshot, webhook, report — is ever handed
+ * ciphertext, because the parser never produces any. A file with nothing to
+ * redact comes back as the very same object.
+ *
+ * The multi-document keys invented by `parseYamlStream` are handed to the
+ * encryption pass explicitly — a SOPS block sits inside each document, not at
+ * the root — and re-recorded on the returned tree, since normalization may have
+ * replaced the object the mark was on.
  * @param {string} filepath
  * @param {string} raw
  * @returns {unknown}
@@ -87,26 +253,26 @@ export function parseContent(filepath, raw) {
       `Supported extensions: ${supported}`
     );
   }
-  try {
-    if (envLike || ext === '.env') {
-      return dotenv.parse(raw);
-    }
 
-    if (iniLike) {
-      return parseIni(raw);
-    }
-
-    if (ext === '.json') {
-      return JSON.parse(raw);
-    }
-
-    if (ext === '.yaml' || ext === '.yml') {
-      const result = yaml.load(raw);
-      return result == null ? {} : result;
-    }
+  // A `.age` file, and any file that opens with the age armor header, is one
+  // opaque blob rather than a config document. There is no structure to parse
+  // and no parser that would not be guessing.
+  if (ext === '.age' || isArmoredAgeFile(raw)) {
+    return opaqueFileState(raw);
+  }
 
-    if (ext === '.toml') {
-      return TOML.parse(raw);
+  let parsed;
+  try {
+    if (envLike || ext === '.env') {
+      parsed = dotenv.parse(raw);
+    } else if (iniLike) {
+      parsed = parseIni(raw);
+    } else if (ext === '.json') {
+      parsed = JSON.parse(raw);
+    } else if (ext === '.yaml' || ext === '.yml') {
+      parsed = parseYamlStream(raw);
+    } else if (ext === '.toml') {
+      parsed = TOML.parse(raw);
     }
   } catch (err) {
     const lineMatch = err.message?.match(/line (\d+)/i);
@@ -115,6 +281,9 @@ export function parseContent(filepath, raw) {
       `Parse error in "${filepath}"${lineInfo}: ${err.message}`
     );
   }
+
+  const keys = documentKeysOf(parsed) ?? [];
+  return withDocumentKeys(normalizeEncrypted(normalizeParsedValue(parsed), keys), keys);
 }
 
 /**