flecto 3.1.0 → 4.0.0

package/src/config.js

@@ -8,7 +8,7 @@ import {
   statSync,
   writeFileSync,
 } from 'fs';
-import { basename, dirname, join, relative, resolve, sep } from 'path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 import fg from 'fast-glob';
 import yaml from 'js-yaml';
 import { isEnvFilename, parseContent } from './parser.js';
@@ -161,6 +161,22 @@ function isInside(candidate, root) {
   return candidate === root || candidate.startsWith(root + sep);
 }
 
+/**
+ * Containment decided on the paths as written, with no symlink resolution and
+ * no canonicalization.
+ *
+ * Used for "was this named inside the project?", where following a link is
+ * exactly the thing that must not happen -- and where canonicalizing one side
+ * but not the other silently breaks on Windows.
+ * @param {string} candidate
+ * @param {string} root both already absolute, from the same base
+ * @returns {boolean}
+ */
+function isLexicallyInside(candidate, root) {
+  const rel = relative(root, candidate);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
 /**
  * Refuse a path that lives inside the project but reads from outside it through
  * a symlink.
@@ -211,7 +227,25 @@ export function assertTargetContained(file, cwd = process.cwd()) {
   // there.
   const nominal = join(canonical(dirname(given)), basename(given));
   // Named from outside the project: nothing was escaped, it was never inside.
-  if (!isInside(nominal, root)) return;
+  //
+  // That judgement must also be made on the path *as given*, not only on a
+  // canonicalized parent -- the parent is a component an untrusted pull request
+  // controls. With a directory symlink (`repo/b -> /outside`),
+  // `canonical(dirname(given))` already points outside, so `nominal` looked
+  // externally-named and this returned without checking anything:
+  // `repo/b/baseline.json` read straight out of the project. Replacing the
+  // *file* with a link was refused; replacing its *directory* was the same
+  // effort and was not.
+  //
+  // That second judgement is deliberately **lexical** -- `resolve(cwd)` against
+  // `resolve(file)`, neither canonicalized. Comparing an as-given path against
+  // a *canonicalized* root is what made the first attempt at this fail on
+  // Windows and leak: `process.cwd()` reports the 8.3 short form
+  // (`C:\Users\RUNNER~1\...`) while `canonical()` returns the long one, so the
+  // two never shared a prefix, the check decided the path was externally named,
+  // and returned. Both sides here derive from the same `process.cwd()` spelling,
+  // so no normalization is needed and none can go wrong.
+  if (!isInside(nominal, root) && !isLexicallyInside(given, resolve(cwd))) return;
 
   const real = canonical(given);
   if (isInside(real, root)) return;
@@ -376,6 +410,178 @@ function nearestExistingDir(path) {
   return { base: current, rest };
 }
 
+/**
+ * Has the operator explicitly opted in to alert actions declared in `.flectorc`?
+ * @returns {boolean}
+ */
+function rcAlertsAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_ALERTS;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Options a pull request can turn into an action or corrupt an existing one,
+ * once it controls `.flectorc`, together with the reason and the CLI flag that
+ * names each one.
+ *
+ * `onAlertFailure` and `deliveryMode` are deliberately not here: `flecto init`
+ * writes them into the generated `.flectorc` itself, they only ever tune how
+ * an alert *already chosen by the operator* responds to failure, and they draw
+ * the same line `failOn` does elsewhere — a setting a repository is meant to
+ * delegate, not an action a settings file grants itself.
+ */
+const ALERT_ACTION_OPTIONS = [
+  ['command', '--command', 'it spawns a shell command on every change'],
+  ['webhook', '--webhook', 'it sends change data to a URL'],
+  ['webhookHeader', '--webhook-header', 'it rides along on every request an operator-approved --webhook makes, and can override headers such as Content-Type'],
+];
+
+/**
+ * Refuse an alert action declared in `.flectorc` rather than on the command
+ * line.
+ *
+ * `watch --command` spawns a shell command on every change, with diff data
+ * injected as `FLECTO_*` environment variables; `--webhook` POSTs that same
+ * data to a URL; `--webhook-header` rides along on that request. All three are
+ * actions, not settings — the same distinction `--update-baseline` draws — and
+ * all three merge through `resolveEffectiveOptions` with no other gate, so a
+ * `.flectorc` (or profile) naming one runs it on the next `flecto watch`. On an
+ * untrusted pull request `.flectorc` is a file the attacker wrote, which makes
+ * an rc-declared `command` unconstrained shell execution, an rc-declared
+ * `webhook` an exfiltration destination the attacker chose, and an rc-declared
+ * `webhookHeader` a way to override what an *operator-approved* webhook call
+ * sends — reachable even when `command`/`webhook` themselves came from the CLI.
+ *
+ * Any of the three named on the CLI is operator intent and unrestricted:
+ * `flecto watch config.yaml --command './notify.sh'` still works exactly as
+ * before. `FLECTO_ALLOW_RC_ALERTS=1` opts out for a repository that genuinely
+ * configures one in `.flectorc`. Refusing loudly rather than skipping silently
+ * is deliberate, for the same reason a stripped plugin or write destination is
+ * loud: an alert that quietly stopped firing would look like "nothing
+ * happened" instead of "this was refused".
+ * @param {Record<string, unknown>} effective
+ * @param {Record<string, unknown>} cliOverrides
+ * @throws {Error} when an alert action came from `.flectorc`/a profile
+ */
+export function assertAlertActionsFromCli(effective, cliOverrides) {
+  if (rcAlertsAllowed()) return;
+  for (const [option, flag, reason] of ALERT_ACTION_OPTIONS) {
+    if (effective[option] === undefined || cliOverrides[option] !== undefined) continue;
+    const declared = Array.isArray(effective[option]) ? effective[option].join(', ') : effective[option];
+    throw new Error(
+      `Refusing "${option}" declared in .flectorc: ${reason}, `
+      + 'and .flectorc is attacker-controlled on an untrusted pull request.\n'
+      + `Declared: ${declared}\n`
+      + `Pass ${flag} on the command line instead, or set FLECTO_ALLOW_RC_ALERTS=1 `
+      + 'if this config is trusted.',
+    );
+  }
+}
+
+/**
+ * Has the operator explicitly opted in to a baseline selected by `.flectorc`?
+ * @returns {boolean}
+ */
+function rcBaselineAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_BASELINE;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Refuse a `snapshotRef` declared in `.flectorc` rather than on the command
+ * line.
+ *
+ * `snapshotRef` names the baseline every change is measured against, so
+ * whoever sets it decides what "changed" means. That makes it an action in the
+ * same sense `--update-baseline` is one: a pull request that controls it can
+ * turn its own failing gate green without touching a policy, a suppression, or
+ * the gate's own `--fail-on`.
+ *
+ * The cheapest exploit needs no crafted value at all. A committed `.flectorc`
+ * carrying `{"defaults": {"snapshotRef": "HEAD"}}` points the baseline at the
+ * pull request's own tip, so every file is compared against itself, every diff
+ * is empty, and `flecto ci` exits 0 no matter what the change did. Confirmed
+ * end to end: a config that disables TLS and raises a pool size 100x fails the
+ * gate against the operator's ref and passes against an rc-declared `HEAD`.
+ *
+ * A ref named on the command line is operator intent and unrestricted, so
+ * `flecto ci config.yaml --snapshot-ref origin/main` is untouched. A repository
+ * that genuinely wants its baseline in the rc file sets
+ * `FLECTO_ALLOW_RC_BASELINE=1`, which is a statement that `.flectorc` is
+ * trusted there. Refusing loudly rather than falling back to a default baseline
+ * is deliberate, for the reason every other gate here refuses loudly: a gate
+ * that quietly measured against something else would still print a clean run.
+ * @param {Record<string, unknown>} effective
+ * @param {Record<string, unknown>} cliOverrides
+ * @throws {Error} when the baseline ref came from `.flectorc`/a profile
+ */
+export function assertSnapshotRefFromCli(effective, cliOverrides) {
+  if (rcBaselineAllowed()) return;
+  // `snapshotFile` picks the baseline just as directly, so it is gated with it
+  // rather than left as the way around it.
+  for (const option of ['snapshotRef', 'snapshotFile']) {
+    if (effective[option] === undefined || cliOverrides[option] !== undefined) continue;
+    throw new Error(
+      `Refusing "${option}" declared in .flectorc: it chooses the baseline every change is`
+      + ' measured against, so a pull request that edits it decides what counts as changed --'
+      + ' pointing it at "HEAD", or at a file it committed, compares every file against itself'
+      + ' and exits 0.\n'
+      + `Declared: ${JSON.stringify(effective[option])}\n`
+      + `Pass --${option === 'snapshotRef' ? 'snapshot-ref' : 'snapshot-file'} on the command line`
+      + ' instead, or set FLECTO_ALLOW_RC_BASELINE=1 if this config is trusted.',
+    );
+  }
+}
+
+/**
+ * Refuse a baseline ref that git would read as an option rather than a
+ * revision.
+ *
+ * The ref reaches `git show <rev>:<path>` as a single argv entry. `execFile`
+ * keeps it out of a shell, so there is no command injection here, but argv is
+ * not the same boundary as a shell: a ref beginning with `-` is still parsed by
+ * git as one of *its* options. `--output=pwned` turns the baseline read into a
+ * file write, and because the read then yields nothing, the baseline parses as
+ * an empty document, every key looks newly `added`, and the default
+ * `--fail-on changed,policy,error` never fires — an arbitrary write and a
+ * silent gate bypass from one string.
+ *
+ * Callers also pass `--end-of-options` so git itself refuses to read any
+ * operand as an option. This check is the belt to that suspenders: it names the
+ * problem in a message a human can act on, and it holds on a git too old for
+ * `--end-of-options` (added in 2.24).
+ * @param {string} ref
+ * @returns {string} the ref, unchanged, when it is safe to pass to git
+ * @throws {Error} when git would read the ref as an option
+ */
+export function assertSafeGitRef(ref) {
+  if (typeof ref !== 'string') {
+    throw new Error('Refusing snapshot ref: it must be a string.');
+  }
+  if (ref.includes('..')) {
+    // `git show A..B` is a *range*: it succeeds and prints nothing, so the
+    // baseline parses empty, every key reads as `added`, and the default
+    // `--fail-on` never fires. Callers resolve refs through
+    // `rev-parse --verify <ref>^{commit}`, which already refuses a range; this
+    // refuses it by name, because "Needed a single revision" explains less. A
+    // valid ref cannot contain `..` in any case (git-check-ref-format).
+    throw new Error(
+      `Refusing snapshot ref "${ref}": ".." makes it a commit range rather than a single`
+      + ' revision, which git reads as an empty diff.',
+    );
+  }
+  if (ref.startsWith('-')) {
+    throw new Error(
+      `Refusing snapshot ref "${ref}": it starts with "-", so git would read it as an option`
+      + ' rather than a revision.',
+    );
+  }
+  if (/[\0\n\r]/.test(ref)) {
+    throw new Error('Refusing snapshot ref: it contains a newline or NUL byte.');
+  }
+  return ref;
+}
+
 /**
  * Split a policy list that may arrive as an array or a comma-separated string.
  * @param {unknown} raw

package/src/drift-sources.js

@@ -0,0 +1,444 @@
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import { assertTargetContained } from './config.js';
+
+/**
+ * Live sources `flecto drift` can read, and the rules that keep reading them
+ * safe (#144).
+ *
+ * Flecto's core promise is that it authenticates to nothing: it reads files,
+ * shells out to nothing but `git`, and touches no key material. `drift` is the
+ * one thing that cannot keep that promise, which is why it is a **separate
+ * binary** with a separate entry point, and why nothing in core imports this
+ * file. Installing Flecto does not enable it; running `flecto ci` cannot reach
+ * it.
+ *
+ * Three rules carry the security of this module.
+ *
+ * **1. Flecto never holds a credential.** It does not read a kubeconfig, an AWS
+ * profile, a token, or an agent socket, and it has no flag that accepts one.
+ * Every source delegates to a CLI the operator has already installed and
+ * already authenticated -- `kubectl`, `aws` -- and inherits whatever that tool
+ * is entitled to. The blast radius of a bug here is therefore bounded by the
+ * credential the operator chose to give that tool, not by anything Flecto
+ * decided. It also means "use a read-only role" is advice the operator can
+ * actually enforce, in their own IAM, rather than a promise we make about our
+ * own code.
+ *
+ * **2. Read-only is structural, not careful.** Every argv is built here, from a
+ * fixed verb allowlist (`ALLOWED_COMMANDS`). Nothing from the URI reaches argv
+ * as a flag: each interpolated component is validated against a conservative
+ * pattern and passed after `--` where the tool supports it. There is no code
+ * path in this file that can construct a mutating command, so "it cannot write"
+ * is a property of the argv table rather than of reviewer attention.
+ *
+ * **3. A value from a secret store is a secret.** Kubernetes Secrets and SSM
+ * SecureStrings are compared **metadata-only**: key presence, and a
+ * length-and-digest shape so a rotation is still visible. The plaintext never
+ * enters a change event, a report, or this process's memory beyond the hashing
+ * call. There is no flag to turn that off, because a flag to print production
+ * secrets is a feature request to answer with "no".
+ */
+
+import { createHmac, randomBytes } from 'crypto';
+
+/**
+ * The complete set of commands this binary may run. Anything not here cannot be
+ * spawned, whatever a URI says.
+ *
+ * Each entry names a tool, a fixed read-only verb, and how to build the rest of
+ * argv from validated components. Adding a mutating verb here is the one change
+ * that would break the read-only property, which is why they live in one table
+ * rather than being assembled at each call site.
+ * @type {Record<string, { tool: string, verbs: string[] }>}
+ */
+const ALLOWED_COMMANDS = {
+  // `verbAt` is which argv position carries the verb: `kubectl get …` puts it
+  // first, while `aws ssm get-parameters-by-path …` names a *service* first.
+  // Gating position 0 for aws would have allowed `ssm put-parameter` through
+  // the check whose docstring calls it "the assertion that keeps it that way".
+  kubectl: { tool: 'kubectl', verbAt: 0, verbs: ['get'] },
+  aws: { tool: 'aws', verbAt: 1, verbs: ['get-parameters-by-path'], services: ['ssm'] },
+};
+
+/** Kubernetes names, per RFC 1123: the pattern the API server itself enforces. */
+const K8S_NAME_RE = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
+/**
+ * SSM parameter paths: printable, slash-delimited, no shell or flag shapes.
+ *
+ * `..` is refused explicitly. AWS would reject a traversing path itself, but
+ * relying on a remote service to validate an argument this process constructed
+ * is the wrong place to draw the line -- and it costs one check to not send it.
+ */
+const SSM_PATH_RE = /^\/(?!.*\.\.)[A-Za-z0-9_.\-/]*$/;
+
+/**
+ * @typedef {{
+ *   kind: 'configmap' | 'secret' | 'ssm' | 'tfstate',
+ *   label: string,
+ *   sensitive: boolean,
+ *   shapedKeys: Set<string>
+ * }} SourceMeta
+ * @typedef {{ state: Record<string, unknown>, meta: SourceMeta }} LiveState
+ */
+
+/**
+ * Refuse a component that could be read as a flag or escape its position.
+ * @param {string} value
+ * @param {RegExp} pattern
+ * @param {string} what
+ * @returns {string}
+ */
+function assertComponent(value, pattern, what) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(`drift: ${what} is required`);
+  }
+  if (value.startsWith('-')) {
+    throw new Error(`drift: ${what} "${value}" starts with "-" and would be read as an option`);
+  }
+  if (!pattern.test(value)) {
+    throw new Error(`drift: ${what} "${value}" is not a valid ${what}`);
+  }
+  return value;
+}
+
+/**
+ * Run an allowlisted read-only command.
+ * @param {keyof typeof ALLOWED_COMMANDS} name
+ * @param {string[]} args argv after the tool, beginning with an allowed verb
+ * @returns {string} stdout
+ */
+function readOnly(name, args) {
+  const entry = ALLOWED_COMMANDS[name];
+  if (!entry) throw new Error(`drift: ${name} is not an allowed command`);
+  if (entry.services && !entry.services.includes(args[0])) {
+    throw new Error(`drift: "${args[0]}" is not an allowed ${name} service`);
+  }
+  if (!entry.verbs.includes(args[entry.verbAt])) {
+    // Unreachable from any URI -- the verb is a literal at each call site. This
+    // is the assertion that keeps it that way.
+    throw new Error(`drift: "${args[entry.verbAt]}" is not a read-only verb for ${name}`);
+  }
+  const run = spawnSync(entry.tool, args, {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    // No shell, ever. And stdin closed: a tool that decides to prompt for
+    // credentials should fail, not hang a CI job forever.
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (run.error?.code === 'ENOENT') {
+    throw new Error(
+      `drift: ${entry.tool} is not installed or not on PATH. flecto drift reads live state through`
+      + ` the tool you have already authenticated -- it holds no credentials of its own.`,
+    );
+  }
+  if (run.status !== 0) {
+    // The tool's own first line is kept, unlike its stdout: an error here is a
+    // diagnostic ("forbidden", "not found", "expired token") that the operator
+    // needs, where stdout is response *data*. Bounded, and attributed, so it is
+    // clear whose words these are.
+    const detail = String(run.stderr ?? '').trim().split('\n')[0].slice(0, 200) || `exit ${run.status}`;
+    throw new Error(`drift: ${entry.tool} failed: ${detail}`);
+  }
+  return run.stdout;
+}
+
+/**
+ * The shape of a secret value: enough to see a rotation, not enough to be one.
+ *
+ * A digest rather than the value means a changed credential still shows up as a
+ * change -- which is the entire point of drift detection -- while the plaintext
+ * never reaches a diff, a report, or a terminal. Truncated because this is a
+ * comparison key, not a commitment.
+ * @param {string} value
+ * @returns {string}
+ */
+const SHAPE_KEY = randomBytes(32);
+
+/**
+ * What a shaped value looks like.
+ *
+ * Exported so the masking decision can be made on the *value* rather than on
+ * the key it sits under: a key name is metadata that can fall out of step with
+ * the value beside it, and when it did, a plaintext printed unmasked because
+ * its key was still marked as shaped.
+ */
+export const SHAPE_RE = /^<\d+ bytes, digest:[0-9a-f]{12}>$/;
+
+function shapeOf(value) {
+  // Keyed with a per-invocation random key, not a bare digest. Both sides of
+  // the comparison are hashed in the same process, so drift detection is
+  // unaffected -- but a bare truncated SHA-256 printed into a CI log is an
+  // offline oracle: 48 bits is trivially brute-forced for a low-entropy secret,
+  // and being unsalted it is a stable cross-run, cross-org identifier for a
+  // shared credential. Keyed, the printed digest is worth nothing to anyone
+  // holding the log.
+  const digest = createHmac('sha256', SHAPE_KEY).update(value, 'utf8').digest('hex').slice(0, 12);
+  return `<${value.length} bytes, digest:${digest}>`;
+}
+
+/**
+ * Replace every value with its shape.
+ * @param {Record<string, unknown>} data
+ * @returns {Record<string, unknown>}
+ */
+function shapesOnly(data) {
+  return Object.fromEntries(
+    Object.entries(data).map(([key, value]) => [key, shapeOf(stableString(value))]),
+  );
+}
+
+/**
+ * A value as a string, without collapsing structure.
+ *
+ * `String(value)` turns every object into `"[object Object]"`, so two different
+ * secrets produced an identical shape and a rotation between them was
+ * invisible -- the one thing shape comparison exists to show.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stableString(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return JSON.stringify(value);
+}
+
+/**
+ * Parse a tool's stdout as JSON without quoting it back on failure.
+ *
+ * `JSON.parse`'s own message quotes the bytes it choked on, and those bytes are
+ * a response from a live secret store. `readTerraformState` already guards this
+ * deliberately; the same reasoning applies to every reader.
+ * @param {string} raw
+ * @param {string} tool
+ * @returns {any}
+ */
+function parseToolJson(raw, tool) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('not an object');
+    }
+    return parsed;
+  } catch {
+    throw new Error(`drift: ${tool} did not return the JSON document expected`);
+  }
+}
+
+/**
+ * Parse a live-source URI into its parts.
+ *
+ * Deliberately strict and hand-written rather than `new URL()`: the shapes are
+ * few and known, and a permissive parser is how a component ends up somewhere
+ * it was not meant to go.
+ * @param {string} uri
+ * @returns {{ scheme: string, rest: string }}
+ */
+export function parseSourceUri(uri) {
+  const match = /^([a-z0-9+.-]{1,16}):\/\/(.*)$/i.exec(String(uri ?? ''));
+  if (!match) {
+    throw new Error(
+      `drift: "${uri}" is not a source URI. Expected one of:\n`
+      + '  k8s://<namespace>/configmap/<name>\n'
+      + '  k8s://<namespace>/secret/<name>      (compared by shape, never by value)\n'
+      + '  ssm://<parameter-path-prefix>        (SecureString compared by shape)\n'
+      + '  tfstate://<path-to-state-file>',
+    );
+  }
+  return { scheme: match[1].toLowerCase(), rest: match[2] };
+}
+
+/**
+ * Read a Kubernetes ConfigMap or Secret.
+ * @param {string} rest `<namespace>/<configmap|secret>/<name>`
+ * @returns {LiveState}
+ */
+function readKubernetes(rest) {
+  const parts = rest.split('/');
+  if (parts.length !== 3) {
+    throw new Error('drift: expected k8s://<namespace>/<configmap|secret>/<name>');
+  }
+  const [namespace, rawKind, name] = parts;
+  const kind = rawKind.toLowerCase();
+  if (kind !== 'configmap' && kind !== 'secret') {
+    throw new Error(`drift: "${rawKind}" is not a readable kind; use configmap or secret`);
+  }
+  assertComponent(namespace, K8S_NAME_RE, 'namespace');
+  assertComponent(name, K8S_NAME_RE, 'name');
+
+  const raw = readOnly('kubectl', [
+    'get', kind, name, '--namespace', namespace, '--output', 'json',
+  ]);
+  /** @type {{ data?: Record<string, string>, stringData?: Record<string, string> }} */
+  const parsed = parseToolJson(raw, 'kubectl');
+  const data = { ...(parsed.data ?? {}), ...(parsed.stringData ?? {}) };
+
+  if (kind === 'secret') {
+    // Values arrive base64-encoded; they are hashed without being decoded, so
+    // the plaintext is never materialized at all.
+    return {
+      state: shapesOnly(data),
+      meta: {
+        kind: 'secret',
+        label: `k8s secret ${namespace}/${name}`,
+        sensitive: true,
+        shapedKeys: new Set(Object.keys(data)),
+      },
+    };
+  }
+  return {
+    state: { ...data },
+    meta: {
+      kind: 'configmap',
+      label: `k8s configmap ${namespace}/${name}`,
+      sensitive: false,
+      shapedKeys: new Set(),
+    },
+  };
+}
+
+/**
+ * Read AWS SSM Parameter Store under a path prefix.
+ *
+ * `--with-decryption` is deliberately **never** passed, so a SecureString comes
+ * back still encrypted and its plaintext never leaves AWS. The ciphertext is
+ * then shaped like any other secret, which still surfaces a rotation.
+ * @param {string} rest the parameter path prefix
+ * @returns {LiveState}
+ */
+function readSsm(rest) {
+  // Built from real segments rather than normalized in place. A single literal
+  // `=== '/'` check left `//`, `/.`, `/./` and `/.//` all reaching the CLI with
+  // a root-equivalent path -- and leaning on AWS to normalize them is the very
+  // thing this module's own SSM_PATH_RE docstring calls the wrong place to draw
+  // the line.
+  const segments = rest.split('/').filter((segment) => segment !== '' && segment !== '.');
+  if (segments.some((segment) => segment === '..')) {
+    throw new Error(`drift: parameter path "${rest}" must not contain ".."`);
+  }
+  if (segments.length === 0) {
+    // `--path / --recursive` is every parameter in the account. One typo would
+    // read another team's namespace, which is the opposite of the
+    // one-named-source-per-invocation rule this tool is built on.
+    throw new Error(
+      'drift: ssm:// needs a parameter path, e.g. ssm:///app/prod.'
+      + ' Reading from the account root would fetch every parameter there.',
+    );
+  }
+  const path = `/${segments.join('/')}`;
+  assertComponent(path, SSM_PATH_RE, 'parameter path');
+
+  const raw = readOnly('aws', [
+    'ssm', 'get-parameters-by-path', '--path', path, '--recursive', '--output', 'json',
+  ]);
+  /** @type {{ Parameters?: Array<{ Name: string, Value: string, Type: string }> }} */
+  const parsed = parseToolJson(raw, 'aws');
+  /** @type {Record<string, unknown>} */
+  const state = Object.create(null);
+  /** @type {Set<string>} */
+  const shapedKeys = new Set();
+  for (const parameter of parsed.Parameters ?? []) {
+    const name = String(parameter.Name);
+    // `slice(path.length)` is a blind cut, so a Name outside the requested path
+    // would derive a key that collides with another. Two parameters deriving
+    // one key is how `state` and `shapedKeys` came to disagree -- a later plain
+    // value overwrote a shaped one while the key stayed marked as shaped, and
+    // the masking exemption then trusted the mark and printed the plaintext.
+    if (!name.startsWith(path)) {
+      throw new Error(`drift: ${name} is not under the requested path ${path}`);
+    }
+    const key = name.slice(path.length).replace(/^\//, '') || name;
+    if (Object.hasOwn(state, key)) {
+      throw new Error(`drift: two parameters resolve to the same key "${key}" under ${path}`);
+    }
+    if (parameter.Type === 'SecureString') {
+      shapedKeys.add(key);
+      state[key] = shapeOf(stableString(parameter.Value));
+    } else {
+      state[key] = parameter.Value;
+    }
+  }
+  return {
+    state,
+    meta: { kind: 'ssm', label: `ssm ${path}`, sensitive: shapedKeys.size > 0, shapedKeys },
+  };
+}
+
+/**
+ * Read outputs from a Terraform state file on disk.
+ *
+ * A local file, so no credential and no network -- and deliberately only the
+ * `outputs` block. Terraform state carries resource attributes including
+ * provider credentials in plenty of real configurations, and walking all of it
+ * would turn a drift check into an exfiltration primitive. Outputs marked
+ * `sensitive` are shaped like any other secret.
+ * @param {string} rest path to the state file
+ * @returns {LiveState}
+ */
+function readTerraformState(rest) {
+  const path = resolve(rest);
+  // Same containment as every other read: a path from outside the project is
+  // operator intent and allowed, but one inside it that escapes through a link
+  // is the shape a pull request can author.
+  assertTargetContained(path, process.cwd());
+  if (!isAbsolute(path) || !existsSync(path) || !statSync(path).isFile()) {
+    throw new Error(`drift: no terraform state file at "${rest}"`);
+  }
+  /** @type {{ outputs?: Record<string, { value: unknown, sensitive?: boolean }> }} */
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    // Deliberately not echoing the parser's message: it quotes the bytes it
+    // choked on, which for a file that is not terraform state means printing a
+    // slice of whatever the file actually was.
+    throw new Error(`drift: "${rest}" is not valid terraform state JSON`);
+  }
+  // Built with fromEntries rather than assignment, so a `__proto__` output is
+  // an ordinary own key: kept and visible in the diff, never reaching
+  // Object.prototype. The three readers now agree on this rule.
+  /** @type {Record<string, unknown>} */
+  const state = Object.create(null);
+  /** @type {Set<string>} */
+  const shapedKeys = new Set();
+  for (const [key, output] of Object.entries(parsed.outputs ?? {})) {
+    if (output?.sensitive) {
+      shapedKeys.add(key);
+      state[key] = shapeOf(stableString(output.value));
+    } else {
+      state[key] = output?.value;
+    }
+  }
+  return {
+    state,
+    meta: {
+      kind: 'tfstate',
+      label: `terraform state ${rest}`,
+      sensitive: shapedKeys.size > 0,
+      shapedKeys,
+    },
+  };
+}
+
+/**
+ * Read the live state a URI names.
+ * @param {string} uri
+ * @returns {LiveState}
+ */
+export function readLiveState(uri) {
+  const { scheme, rest } = parseSourceUri(uri);
+  switch (scheme) {
+    case 'k8s':
+    case 'kubernetes':
+      return readKubernetes(rest);
+    case 'ssm':
+      return readSsm(rest);
+    case 'tfstate':
+      return readTerraformState(rest);
+    default:
+      throw new Error(`drift: "${scheme}://" is not a supported source`);
+  }
+}
+
+export { shapeOf, ALLOWED_COMMANDS };