flecto 3.0.2 → 3.1.0

package/src/config.js

@@ -1,4 +1,13 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'fs';
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
 import { basename, dirname, join, relative, resolve, sep } from 'path';
 import fg from 'fast-glob';
 import yaml from 'js-yaml';
@@ -216,6 +225,157 @@ export function assertTargetContained(file, cwd = process.cwd()) {
   );
 }
 
+/**
+ * Has the operator explicitly opted in to write destinations that `.flectorc`
+ * points outside the project?
+ * @returns {boolean}
+ */
+function rcWritesAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_WRITES;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Refuse a *write* destination that leaves the project.
+ *
+ * The read rule ({@link assertTargetContained}) is about escape, and treats a
+ * path named from outside the project as operator intent. A write cannot be read
+ * that way, because the path is not always the operator's: `output` and
+ * `baseline` can be declared in `.flectorc`, and on an untrusted pull request
+ * `.flectorc` is attacker-controlled. Both destinations carry content the
+ * attacker partly controls — the report embeds config values and file names, a
+ * baseline embeds rule ids, paths, and messages — so an unconstrained
+ * destination is an arbitrary file overwrite with partly chosen content, which
+ * on a CI runner is a shell profile, a workflow file, or an SSH config.
+ *
+ * Two rules, matching the provenance:
+ *
+ * - **Declared in `.flectorc`** — must resolve inside the project.
+ *   `FLECTO_ALLOW_RC_WRITES=1` opts out, for a repository that genuinely
+ *   configures a destination elsewhere.
+ * - **Any source** — must not leave the project through a symlink, on the path
+ *   itself or on the directory it is written into. That is the shape a pull
+ *   request can author without touching the workflow, and it is refused for the
+ *   same reason a symlinked *target* is; `FLECTO_ALLOW_SYMLINK_TARGETS=1` opts
+ *   out of this half, as it does for reads.
+ *
+ * Refusing loudly rather than falling back to a default path is deliberate: a
+ * report that silently went somewhere else is worse than one that was not
+ * written.
+ * @param {string} file destination path, already resolved against the cwd
+ * @param {{ option: string, fromCli?: boolean, cwd?: string }} context
+ * @throws {Error} when the destination escapes the project
+ */
+export function assertWriteDestinationContained(file, context) {
+  const { option, fromCli = false } = context;
+  const cwd = context.cwd ?? process.cwd();
+  const lexicalRoot = resolve(cwd);
+  const root = canonical(lexicalRoot);
+  const given = resolve(cwd, file);
+  const shown = relative(lexicalRoot, given).split(sep).join('/') || given;
+
+  // A destination need not exist yet, and neither need the directories above it,
+  // so normalize from the nearest ancestor that does: canonical() cannot resolve
+  // a path that is not there, and its fallback leaves the spelling as written —
+  // which on Windows is an 8.3 short name that compares as a different directory
+  // from the long form `root` carries, making an in-project path look external.
+  const { base, rest } = nearestExistingDir(dirname(given));
+  const nominal = join(canonical(base), ...rest, basename(given));
+  // Either spelling counts as inside: the lexical form covers a path derived
+  // from the cwd, the canonical form a path named some other way.
+  const insideProject = isInside(given, lexicalRoot) || isInside(nominal, root);
+
+  if (!fromCli && !rcWritesAllowed() && !insideProject) {
+    throw new Error(
+      `Refusing to write "${option}" to ${given}: .flectorc points it outside the project.\n`
+      + '.flectorc is attacker-controlled on an untrusted pull request, and this file carries '
+      + 'config values and file names into whatever it overwrites.\n'
+      + `Pass ${option} on the command line for a destination outside the project, or set `
+      + 'FLECTO_ALLOW_RC_WRITES=1 if this repository genuinely configures one.',
+    );
+  }
+
+  if (symlinkTargetsAllowed()) return;
+
+  // Two ways a write leaves through a link: the destination is itself a link, or
+  // the nearest directory that exists on the way to it is. The second covers a
+  // path several levels deep whose parents have not been created yet.
+  for (const candidate of [given, base]) {
+    const real = linkDestination(candidate);
+    // Nothing there at all: no link to follow, so nothing to refuse.
+    if (real === null) continue;
+    // Named from outside the project: nothing escaped, it was never inside.
+    if (!isInside(candidate, lexicalRoot)) continue;
+    if (isInside(real, root)) continue;
+    throw new Error(
+      `Refusing to write "${option}" to "${shown}": it is a link out of the project, `
+      + `resolving to ${real}.\n`
+      + 'File names and links are attacker-controlled on an untrusted pull request, and '
+      + 'writing through one would overwrite a file outside the repository.\n'
+      + 'Set FLECTO_ALLOW_SYMLINK_TARGETS=1 if this link is intentional.',
+    );
+  }
+}
+
+/**
+ * How many links to walk before giving up. The OS gives up around 40; this only
+ * needs to outlast any chain a repository would legitimately contain.
+ */
+const MAX_LINK_HOPS = 32;
+
+/**
+ * Where a path actually lands, following links even when the chain ends
+ * somewhere that does not exist yet.
+ *
+ * `existsSync` follows links, so it reports *nothing* for a link whose target is
+ * missing — and `realpathSync` fails on one, leaving {@link canonical} to fall
+ * back to the path as written, which is still inside the project. So a link to a
+ * file the runner does not have yet reads as contained twice over. That is not
+ * the weaker half of this attack but the stronger one: overwriting needs the
+ * file to already be there, while a link to a file the runner does *not* have
+ * yet has Flecto create it. `~/.ssh/authorized_keys` is the one that stings,
+ * because sshd skips lines it cannot parse, so HTML wrapped around one
+ * attacker-authored line is still a usable key file.
+ *
+ * So the link is resolved by hand, hop by hop, and judged wherever it ends up.
+ * @param {string} path
+ * @param {number} [depth]
+ * @returns {string | null} null when there is nothing at `path` at all
+ */
+function linkDestination(path, depth = 0) {
+  const stats = lstatSync(path, { throwIfNoEntry: false });
+  if (!stats) return null;
+  if (!stats.isSymbolicLink()) return canonical(path);
+
+  const target = resolve(dirname(path), readlinkSync(path));
+  // A cycle, or a chain long enough that the write would fail with ELOOP
+  // anyway: judge the hop we have rather than walking forever.
+  if (depth >= MAX_LINK_HOPS) return target;
+  // The next hop may not exist; normalize what is there and keep the rest as
+  // written, the same way an ordinary destination is normalized above.
+  const { base, rest } = nearestExistingDir(dirname(target));
+  return linkDestination(target, depth + 1) ?? join(canonical(base), ...rest, basename(target));
+}
+
+/**
+ * The nearest ancestor of a path that exists on disk, plus the segments below it
+ * that do not.
+ * @param {string} path
+ * @returns {{ base: string, rest: string[] }}
+ */
+function nearestExistingDir(path) {
+  let current = resolve(path);
+  /** @type {string[]} */
+  const rest = [];
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) break;
+    rest.unshift(basename(current));
+    current = parent;
+  }
+  return { base: current, rest };
+}
+
 /**
  * Split a policy list that may arrive as an array or a comma-separated string.
  * @param {unknown} raw

package/src/differ.js

@@ -179,6 +179,49 @@ function matchParts(patternParts, pathParts) {
   return true;
 }
 
+/**
+ * The containers on the path currently being compared, one set per side.
+ *
+ * A cyclic tree makes the walk reach a node it is already inside. Descending
+ * again cannot find anything the in-progress comparison will not already report
+ * at a shorter path, so the back-edge is dropped rather than followed. Same
+ * ancestor-tracking pattern as `normalizeParsedValue` in parser.js and
+ * `collectLeaves` in policy.js: added on the way in, removed on the way out, so
+ * a value merely reached twice by separate branches (a DAG, not a cycle) is
+ * still compared in full on each branch.
+ *
+ * Either side repeating is enough to stop. Tracking the *pair* instead would be
+ * more precise -- it would keep descending where one side cycles and the other
+ * does not -- but two cyclic trees have |before| x |after| distinct pairs, so
+ * precision there buys a quadratic worst case. This is a guard against a walk
+ * that will not end; bounding it by the size of the input is the property worth
+ * having.
+ *
+ * Nothing downstream of the parser holds a cycle -- `normalizeParsedValue`
+ * replaces one with its circular sentinel before a tree ever gets here -- so
+ * this is a second line rather than the first. Without it the walk recurses
+ * until the stack overflows, which costs real time on the way down (the path
+ * string is rebuilt at every level) before throwing.
+ *
+ * This covers the structural walk only. `arraySignature` canonicalizes without
+ * it -- that runs per array element, where the same tracking cost ~15% on a
+ * 5000-element diff, and its `catch` already contains a cyclic element by
+ * falling back to identity comparison.
+ *
+ * It is not free: the set writes cost ~20% of `diffTrees`, which the benchmark
+ * puts at ~17% of a run, so ~3% end to end. Gating it behind a depth threshold
+ * removes that, and was tried -- but then a cycle is followed as far as the
+ * threshold, and every level of it emits a duplicate event under a
+ * `self.self.self...` path. Paying 3% to keep the output right is the better
+ * trade for a tool whose output is read on a pull request.
+ * @typedef {{ before: Set<object>, after: Set<object> }} Ancestors
+ */
+
+/** @returns {Ancestors} */
+function newAncestors() {
+  return { before: new Set(), after: new Set() };
+}
+
 /**
  * Recursively diff two values at a given key path.
  * @param {unknown} before
@@ -186,8 +229,9 @@ function matchParts(patternParts, pathParts) {
  * @param {string} path
  * @param {ChangeEvent[]} events  accumulator
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} ancestors  containers on the current path
  */
-function diffValues(before, after, path, events, options = {}) {
+function diffValues(before, after, path, events, options = {}, ancestors = newAncestors()) {
   const beforeIsObj = isPlainObject(before);
   const afterIsObj = isPlainObject(after);
   const beforeIsArr = Array.isArray(before);
@@ -195,13 +239,23 @@ function diffValues(before, after, path, events, options = {}) {
 
   // Both plain objects → recurse into keys
   if (beforeIsObj && afterIsObj) {
-    diffObjects(before, after, path, events, options);
+    if (ancestors.before.has(before) || ancestors.after.has(after)) return;
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffObjects(before, after, path, events, options, ancestors);
+    ancestors.before.delete(before);
+    ancestors.after.delete(after);
     return;
   }
 
   // Both arrays → diff by index or identity key
   if (beforeIsArr && afterIsArr) {
-    diffArrays(before, after, path, events, options);
+    if (ancestors.before.has(before) || ancestors.after.has(after)) return;
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffArrays(before, after, path, events, options, ancestors);
+    ancestors.before.delete(before);
+    ancestors.after.delete(after);
     return;
   }
 
@@ -247,8 +301,9 @@ function diffValues(before, after, path, events, options = {}) {
  * @param {string} basePath
  * @param {ChangeEvent[]} events
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} [ancestors]
  */
-function diffObjects(before, after, basePath, events, options = {}) {
+function diffObjects(before, after, basePath, events, options = {}, ancestors = newAncestors()) {
   const beforeKeys = new Set(Object.keys(before));
   const afterKeys = new Set(Object.keys(after));
 
@@ -272,7 +327,7 @@ function diffObjects(before, after, basePath, events, options = {}) {
   for (const key of beforeKeys) {
     if (afterKeys.has(key)) {
       const childPath = basePath ? `${basePath}.${key}` : key;
-      diffValues(before[key], after[key], childPath, events, options);
+      diffValues(before[key], after[key], childPath, events, options, ancestors);
     }
   }
 }
@@ -366,8 +421,9 @@ function arraySignature(value) {
  * @param {string} basePath
  * @param {ChangeEvent[]} events
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} [ancestors]
  */
-function diffArrays(before, after, basePath, events, options = {}) {
+function diffArrays(before, after, basePath, events, options = {}, ancestors = newAncestors()) {
   const idKey = resolveArrayIdKey(before, after, options);
 
   if (idKey) {
@@ -380,7 +436,7 @@ function diffArrays(before, after, basePath, events, options = {}) {
         if (!beforeMap.has(key)) {
           events.push({ type: 'added', path: childPath, after: afterItem.value });
         } else {
-          diffValues(beforeMap.get(key).value, afterItem.value, childPath, events, options);
+          diffValues(beforeMap.get(key).value, afterItem.value, childPath, events, options, ancestors);
         }
       }
       for (const [key, beforeItem] of beforeMap) {
@@ -424,7 +480,7 @@ function diffArrays(before, after, basePath, events, options = {}) {
     } else if (i >= after.length) {
       events.push({ type: 'removed', path: childPath, before: before[i] });
     } else {
-      diffValues(before[i], after[i], childPath, events, options);
+      diffValues(before[i], after[i], childPath, events, options, ancestors);
     }
   }
 }
@@ -447,14 +503,22 @@ export function diffTrees(before, after, options = {}) {
     arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
   };
 
-  // Root handling: avoid assuming object roots.
+  // Root handling: avoid assuming object roots. The roots are recorded here
+  // because these two calls bypass `diffValues`, which is where every other
+  // container is recorded -- without it a cycle back to the root would be
+  // caught one level deeper than it should be.
+  const ancestors = newAncestors();
   if (isPlainObject(before) && isPlainObject(after)) {
-    diffObjects(before, after, '', events, diffOpts);
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffObjects(before, after, '', events, diffOpts, ancestors);
   } else if (Array.isArray(before) && Array.isArray(after)) {
-    diffArrays(before, after, '', events, diffOpts);
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffArrays(before, after, '', events, diffOpts, ancestors);
   } else {
     // Compare as a single root value. Use "<root>" so we can still ignore it if desired.
-    diffValues(before, after, '<root>', events, diffOpts);
+    diffValues(before, after, '<root>', events, diffOpts, ancestors);
   }
 
   // Encrypted files carry signals a key-by-key walk cannot express: the file

package/src/pr-comment.js

@@ -296,6 +296,33 @@ async function errorDetail(response, token) {
   return safe ? `: ${safe}` : '';
 }
 
+/**
+ * @param {Response} response
+ * @returns {boolean}
+ */
+function isRedirect(response) {
+  // `redirect: 'manual'` surfaces the 3xx itself in Node; a browser-shaped
+  // opaque redirect reports status 0 with `type: 'opaqueredirect'`.
+  return (response.status >= 300 && response.status < 400) || response.type === 'opaqueredirect';
+}
+
+/**
+ * The origin a redirect points at, for the error message. Only the origin: the
+ * rest of a `Location` is not worth echoing into a log.
+ * @param {Response} response
+ * @param {string} url
+ * @returns {string}
+ */
+function redirectTarget(response, url) {
+  const location = response.headers?.get?.('location');
+  if (!location) return '';
+  try {
+    return ` to ${new URL(location, url).origin}`;
+  } catch {
+    return '';
+  }
+}
+
 /**
  * @param {{ fetchImpl: typeof fetch, provider: object, url: string, method: string, token: string, body?: unknown, timeoutMs: number }} request
  * @returns {Promise<Response>}
@@ -315,6 +342,13 @@ async function apiRequest({ fetchImpl, provider, url, method, token, body, timeo
       },
       body: body === undefined ? undefined : JSON.stringify(body),
       signal: controller.signal,
+      // Never follow a redirect with a credential attached. `fetch` strips
+      // `Authorization` when a redirect crosses origins, but it strips *only*
+      // that header — GitLab authenticates with `PRIVATE-TOKEN`, which is
+      // forwarded to wherever the API host points, verified against a local
+      // server. Refusing the redirect is the whole fix: these endpoints do not
+      // legitimately redirect, and one that does is worth seeing.
+      redirect: 'manual',
     });
   } catch (err) {
     const reason = err?.name === 'AbortError'
@@ -325,6 +359,14 @@ async function apiRequest({ fetchImpl, provider, url, method, token, body, timeo
     clearTimeout(timer);
   }
 
+  if (isRedirect(response)) {
+    throw new Error(
+      `${provider.label} API ${method} was redirected (HTTP ${response.status}`
+      + `${redirectTarget(response, url)}), and Flecto does not follow a redirect with an API`
+      + ' token attached. Point the API URL at the host that answers directly.',
+    );
+  }
+
   if (!response.ok) {
     throw new Error(
       `${provider.label} API ${method} returned HTTP ${response.status}${await errorDetail(response, token)}`,

package/src/pr-providers.js

@@ -229,8 +229,15 @@ const bitbucket = {
   readOne: (payload) => ({ url: payload?.links?.html?.href }),
 };
 
+/**
+ * Comments collection for the pull request. The workspace and slug are encoded
+ * for the same reason GitLab's project id is: they are interpolated into a URL
+ * path, and a value carrying `/`, `?`, or `#` would otherwise restructure the
+ * request rather than name a repository.
+ */
 function bitbucketCommentsBase(c) {
-  return `${c.apiUrl}/repositories/${c.workspace}/${c.repoSlug}/pullrequests/${c.prNumber}/comments`;
+  return `${c.apiUrl}/repositories/${encodeURIComponent(c.workspace)}`
+    + `/${encodeURIComponent(c.repoSlug)}/pullrequests/${c.prNumber}/comments`;
 }
 
 /** Detection order. GitHub stays first so its behavior is unchanged. */

package/src/renderer.js

@@ -1,20 +1,8 @@
 import chalk from 'chalk';
-import { redactSecretString } from './secrets.js';
+import { looksLikeSecretPath, redactSecretString } from './secrets.js';
 import { ENCRYPTED_DISPLAY, displayEncrypted, isEncryptedSentinel } from './encrypted.js';
 import { secretMatchPath } from './differ.js';
 
-/**
- * Key names that mean "this value is a credential".
- *
- * Matched against the *configuration* path only. A multi-document file prefixes
- * every path with the document's identity — `Deployment/prod/token-service.…` —
- * and that identity is a resource name the user chose, not a key name. Letting
- * it match here masked every value in the document, numbers and booleans
- * included, so the path reaching this regex is always the one
- * {@link secretMatchPath} produced.
- */
-const SECRET_PATH_RE = /(secret|token|password|api[_-]?key|private[_-]?key|credential)/i;
-
 /**
  * Format a scalar value for display. Strings get quoted; others are JSON-stringified.
  * @param {unknown} v
@@ -28,7 +16,7 @@ function fmt(v, opts = {}) {
   if (isEncryptedSentinel(v)) return chalk.dim(ENCRYPTED_DISPLAY);
   let value = displayEncrypted(v);
   if (opts.maskSecrets) {
-    if (opts.path && SECRET_PATH_RE.test(opts.path)) {
+    if (opts.path && looksLikeSecretPath(opts.path)) {
       return chalk.dim('"***"');
     }
     // The changed path itself can look benign while the value carries secrets,
@@ -202,7 +190,7 @@ export function renderPolicyFindings(findings) {
  * @returns {unknown}
  */
 export function maskSensitiveValue(value, path = '') {
-  if (SECRET_PATH_RE.test(path)) return '***';
+  if (looksLikeSecretPath(path)) return '***';
   if (Array.isArray(value)) {
     return value.map((v, i) => maskSensitiveValue(v, `${path}[${i}]`));
   }

package/src/report.js

@@ -31,7 +31,8 @@ import { isAbsolute, relative } from 'path';
  *   cwd?: string,
  *   version?: string,
  *   limit?: number,
- *   maskSecrets?: boolean
+ *   maskSecrets?: boolean,
+ *   store?: string
  * }} ReportData
  */
 
@@ -657,7 +658,8 @@ function footer(data) {
   const limit = Number.isInteger(data.limit)
     ? ` Limited to the ${escapeHtml(plural(data.limit, 'most recent snapshot'))}.`
     : '';
-  return '<footer>Generated by Flecto from <code>.flecto-snapshots/</code>.'
+  const store = escapeHtml(String(data.store ?? '.flecto-snapshots/'));
+  return `<footer>Generated by Flecto from <code>${store}</code>.`
     + ' This file is self-contained: no external scripts, fonts, or images, and nothing'
     + ` is sent anywhere when you open it.${limit}</footer>`;
 }

package/src/secrets.js

@@ -330,6 +330,33 @@ export function redactSecretString(value) {
   return out + value.slice(cursor);
 }
 
+/**
+ * Key names that mean "this value is a credential".
+ *
+ * Matched against the *configuration* path only. A multi-document file prefixes
+ * every path with the document's identity — `Deployment/prod/token-service.…` —
+ * and that identity is a resource name the user chose, not a key name. Letting
+ * it match masks every value in the document, numbers and booleans included, so
+ * callers strip the document prefix before matching: see `secretMatchPath` in
+ * differ.js, and the document handling in `maskState`.
+ */
+export const SECRET_PATH_RE = /(secret|token|password|api[_-]?key|private[_-]?key|credential)/i;
+
+/**
+ * True when a configuration path names a credential.
+ *
+ * Lives here rather than beside either caller because there are two of them —
+ * the renderer masking a diff for display, and the snapshot store masking a
+ * state for a commit — and a store that recognized fewer key names than the
+ * terminal did would write into git history exactly the values the terminal
+ * thought were too sensitive to print.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function looksLikeSecretPath(path) {
+  return SECRET_PATH_RE.test(path);
+}
+
 /**
  * True when a value — or any string nested inside a plain object or array —
  * looks like a secret.