@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/src/lint/secret-shape.ts

@@ -0,0 +1,159 @@
+/**
+ * The two heuristics the secrets rules of the TF family share: does this
+ * attribute's NAME read like a credential, and does its VALUE look like one.
+ *
+ * tfsec shipped `general-secrets-sensitive-in-variable`,
+ * `-in-local` and `-in-attribute`, and trivy dropped all three when it
+ * absorbed tfsec, so no maintained tool checks them today (#2107's survey).
+ * TF007, TF008, TF009 and TF022 are chant's versions, and they only stay
+ * consistent with each other if "secret-shaped" means one thing. That is what
+ * this module is.
+ *
+ * Nothing here re-implements a detector `packages/core/src/audit/secrets.ts`
+ * already has. The value heuristic runs a candidate through `scanForSecrets`
+ * first, so every vendor prefix the SEC family knows (AWS key ids, GitHub,
+ * Slack, Google, Stripe), the PEM block shape and the connection-string shape
+ * are recognised here for free, and it reuses that module's placeholder
+ * vocabulary, its identifier-slug filter and its entropy function. What it
+ * adds is what a Terraform attribute needs and a raw text scan does not: the
+ * JWT and bare PEM-header shapes, and a lower length floor than SEC010's 24
+ * characters, because an attribute value is already a single token rather
+ * than a line of prose to fish tokens out of.
+ */
+
+import {
+  looksLikeIdentifierSlug,
+  looksLikePlaceholder,
+  scanForSecrets,
+  shannonEntropy,
+} from "@intentius/chant/audit/secrets";
+
+/**
+ * Credential words, matched against the whole attribute name on `_`
+ * boundaries, so `db_password` and `access_key` match but `keystore` and
+ * `tokenizer` do not.
+ */
+const SECRET_NAME_RE = /(^|_)(password|passwd|secret|token|api_key|private_key|access_key)(_|$)/;
+
+/**
+ * Suffixes that turn a credential word into a REFERENCE to a credential:
+ * `secret_arn`, `db_password_file`, `api_key_id`, `private_key_path`,
+ * `token_name`. The value under one of these is a locator, and a locator is
+ * exactly what the fix for the other rules asks for, so flagging it would
+ * flag the remediation.
+ */
+const LOCATOR_SUFFIX_RE = /_(file|path|arn|id|name)$/;
+
+/** Minimum length for a value to be worth judging at all. */
+export const MIN_SECRET_LENGTH = 8;
+
+/** Minimum length for the generic high-entropy shape (below it, entropy says nothing). */
+const MIN_ENTROPY_LENGTH = 16;
+
+/** Bits per character above which a token of that length reads as random. */
+const ENTROPY_THRESHOLD = 3.5;
+
+/** `eyJ...header.eyJ...payload.signature`. An unsigned JWT still carries claims. */
+const JWT_RE = /^ey[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(\.[A-Za-z0-9_-]*)?$/;
+
+/** A PEM header on its own, without the closing block `scanForSecrets` requires. */
+const PEM_HEADER_RE = /-----BEGIN ([A-Z]+ )?PRIVATE KEY-----/;
+
+/** Normalize an attribute or variable name for the name heuristic. */
+function normalizeName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+
+/**
+ * Does this attribute or variable name read like a credential? Case-insensitive
+ * and word-bounded, with the locator suffixes excluded.
+ */
+export function isSecretName(name: string): boolean {
+  const normalized = normalizeName(name);
+  if (LOCATOR_SUFFIX_RE.test(normalized)) return false;
+  return SECRET_NAME_RE.test(normalized);
+}
+
+/**
+ * Is this a plain string literal, as opposed to an expression? `hcl2json`
+ * renders every expression as a `"${...}"` template, so a value carrying one
+ * is a reference (`var.db_password`, `data.aws_secretsmanager_secret_version.x.secret_string`)
+ * or an interpolation, never a committed constant. Those are the fix, not the
+ * finding.
+ */
+export function isLiteralString(value: unknown): value is string {
+  return typeof value === "string" && !value.includes("${");
+}
+
+/**
+ * A placeholder rather than a credential. Core's list is checked twice: once
+ * as written, once with separators stripped, so the `CHANGE_ME` and
+ * `YOUR_API_KEY` spellings land on the same `changeme` / `your-api-key`
+ * entries as the unseparated ones.
+ */
+export function isPlaceholderValue(value: string): boolean {
+  return looksLikePlaceholder(value) || looksLikePlaceholder(value.replace(/[-_\s]/g, ""));
+}
+
+/** At least 3 of {lower, upper, digit, symbol}, which cuts plain words and pure hex. */
+function hasClassDiversity(value: string): boolean {
+  let classes = 0;
+  if (/[a-z]/.test(value)) classes++;
+  if (/[A-Z]/.test(value)) classes++;
+  if (/[0-9]/.test(value)) classes++;
+  if (/[^A-Za-z0-9]/.test(value)) classes++;
+  return classes >= 3;
+}
+
+/** The generic shape: a long, diverse, high-entropy token that isn't a slug. */
+function isHighEntropyToken(value: string): boolean {
+  if (value.length < MIN_ENTROPY_LENGTH) return false;
+  if (!/^[A-Za-z0-9+/=_-]+$/.test(value)) return false;
+  if (!hasClassDiversity(value)) return false;
+  if (looksLikeIdentifierSlug(value)) return false;
+  return shannonEntropy(value) >= ENTROPY_THRESHOLD;
+}
+
+/**
+ * Does this value look like a live credential on its own, whatever it is
+ * called? A known vendor shape (through core's detectors), a JWT, a PEM key,
+ * or a high-entropy token.
+ */
+export function isCredentialShapedValue(value: unknown): boolean {
+  if (!isLiteralString(value)) return false;
+  if (value.length < MIN_SECRET_LENGTH) return false;
+  if (isPlaceholderValue(value)) return false;
+  if (JWT_RE.test(value)) return true;
+  if (PEM_HEADER_RE.test(value)) return true;
+  // Core's own scan, over the single value: every SEC00x detector plus its
+  // high-entropy catch-all, with no file to walk.
+  if (scanForSecrets([{ path: "value", content: value }]).length > 0) return true;
+  return isHighEntropyToken(value);
+}
+
+/** Which heuristic fired, so a diagnostic can say why it is complaining. */
+export type SecretShapeReason = "name" | "value";
+
+export interface SecretShape {
+  reason: SecretShapeReason;
+  /** The value's length, for a message that never quotes the value itself. */
+  length: number;
+}
+
+/**
+ * The combined test the rules use: is `value`, assigned to an attribute called
+ * `name`, a committed secret? Either heuristic is enough, but both sides of the
+ * gate are the same, since the value has to be a literal, long enough to be a
+ * credential, and not a placeholder, so `sensitive = true`-style
+ * remediation advice is never given for `password = "changeme"`.
+ *
+ * Findings never carry the value. Callers get the reason and the length.
+ */
+export function secretShapedAssignment(name: string, value: unknown): SecretShape | undefined {
+  if (!isLiteralString(value)) return undefined;
+  if (value.length < MIN_SECRET_LENGTH) return undefined;
+  if (isPlaceholderValue(value)) return undefined;
+  if (isCredentialShapedValue(value)) return { reason: "value", length: value.length };
+  if (isSecretName(name)) return { reason: "name", length: value.length };
+  return undefined;
+}

package/src/live-ownership.ts

@@ -0,0 +1,60 @@
+/**
+ * The live root's ownership channel (#2104): choudoufu's two marker tags.
+ *
+ * Sibling of `./state-ownership.ts`, and here for the same mechanical reason:
+ * `plugin.ts` declares `ownershipChannel` eagerly while `describeResources`
+ * is behind a dynamic import, so the key names cannot live in the reader
+ * without dragging the reader, and `node:child_process` with it, into every
+ * plugin load.
+ *
+ * ## Why the keys are declared and the verdicts are set by hand
+ *
+ * The issue that added this asked which of two ways to go: widen core's
+ * `OwnershipChannel` so a lexicon can supply its own classifier, or declare
+ * the keys for discoverability and set the verdicts in the reader, the way
+ * `lexicons/fly/src/ownership.ts` does for its two tiers. The second, and the
+ * reason is that the first buys nothing.
+ *
+ * Core's `classifyOwnership` tests one thing: does `tags[keys.managedBy]`
+ * equal the literal `"chant"`. Nothing in core ever calls it on a lexicon's
+ * behalf. `packages/core/src/ownership.ts` exports it, every lexicon calls it
+ * itself where the test happens to fit, and the ones it does not fit, fly's
+ * app boundary and aws's stack tags, already set verdicts directly. Adding a
+ * `classify` member to `OwnershipChannel` would give core a field only this
+ * lexicon passes and only this lexicon reads back, which is a longer way of
+ * writing the function `./describe-resources.ts` already has.
+ *
+ * What the declaration is still for is the claim it makes. Declaring
+ * `describeResources` on the channel is what turns the observation
+ * conformance suite's ownership assertion from a shape check into a
+ * behavioural one, and that claim holds on a live root exactly as it does on
+ * a stock one, from a different reading. The suite runs for both modes in
+ * `./describe-resources.test.ts`.
+ *
+ * ## The keys, and the slot that does not fit
+ *
+ * `ChannelKeys` is a managed-by / stack / env triple, because everywhere else
+ * chant stamps three tags. choudoufu's marker is two tags and no managed-by
+ * key at all: per `live/MARKERS.md`'s "Ownership semantics", a resource
+ * carrying `tofu-estate` belongs to that estate and there is no secondary
+ * check, so `tofu-estate` is both the managed-by claim and the stack
+ * identity. `tofu-address` takes the third slot because it is the marker's
+ * other half, not because it is an environment: a choudoufu marker has no
+ * environment in it, which is why `ResourceMetadata.marker` on a live read
+ * carries the estate as its `stack` and leaves `env` absent rather than
+ * filling it with an address.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/**
+ * The two tag keys `live/MARKERS.md` spec version 1 defines, named here so a
+ * reader of the plugin can see what a live root's verdict is read from.
+ * `./hcl/marker.ts` holds the constants the reader itself uses, along with
+ * the escaping and the ownership semantics that go with them.
+ */
+export const TERRAFORM_LIVE_MARKER_KEYS: ChannelKeys = {
+  managedBy: "tofu-estate",
+  stack: "tofu-estate",
+  env: "tofu-address",
+};

package/src/lsp/completions.test.ts

@@ -91,7 +91,8 @@ describe("LSP completions", () => {
     const labels = items.map((i) => i.label);
     expect(labels).toContain("gate");
     expect(labels).toContain("compensate");
-    expect(labels).toContain("taskQueue");
+    expect(labels).toContain("gateTimeout");
+    expect(labels).not.toContain("taskQueue");
   });
 
   it("completes a builder's own opts keys inside its second argument", () => {
@@ -103,7 +104,7 @@ describe("LSP completions", () => {
   it("completes root-entry keys inside chant.config.ts's terraform.roots.<name>", () => {
     const content = "export default {\n  terraform: {\n    roots: {\n      app: {\n        ";
     const items = completions(ctx({ content, position: { line: 4, character: 8 } }));
-    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "dir", "varFiles", "workspace"]);
+    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "delete", "dir", "varFiles", "workspace"]);
   });
 
   it("completes the terraform namespace's own top-level keys", () => {

package/src/lsp/option-keys.ts

@@ -15,7 +15,7 @@ export interface OptionKey {
 
 /** `TerraformConfig`'s own top-level keys (`terraform: { <here> }`). */
 export const CONFIG_NAMESPACE_KEYS: OptionKey[] = [
-  { key: "binary", detail: '"terraform" | "tofu" — which CLI drives the roots. Default: "terraform".' },
+  { key: "binary", detail: '"terraform" | "tofu" | "choudoufu" — which CLI drives the roots. Default: "terraform".' },
   { key: "roots", detail: "Named root modules. The name is the entity-key prefix." },
 ];
 
@@ -25,21 +25,22 @@ export const ROOT_ENTRY_KEYS: OptionKey[] = [
   { key: "workspace", detail: "Terraform workspace to select for this root. Omitted means `default`." },
   { key: "varFiles", detail: "`-var-file` arguments, in order, relative to `dir`." },
   { key: "backendConfig", detail: "`-backend-config` key/value pairs handed to `init`." },
+  { key: "delete", detail: '"never" | "owned-only" | "gated" — this root\'s delete mode, mapped onto choudoufu\'s policy block on a live root.' },
 ];
 
 /** `TerraformApplyOpConfig`'s keys (`TerraformApplyOp({ <here> })`). */
 export const APPLY_OP_KEYS: OptionKey[] = [
-  { key: "name", detail: "Op name (kebab-case). Also the default task queue and gate signal suffix." },
+  { key: "name", detail: "Op name (kebab-case). `gateName` defaults to `approve-<name>`." },
   { key: "root", detail: "Key into the project's `terraform.roots`." },
   { key: "planFile", detail: "Plan file written by Plan and consumed by Apply. Default: `chant.tfplan`." },
   { key: "gate", detail: '"on-destroy" | "always" | "never" — when to emit the approval gate. Default: "on-destroy".' },
-  { key: "signalName", detail: "Gate signal name. Default: `approve-<name>`." },
-  { key: "gateTimeout", detail: "Temporal duration the gate waits before timing out. Default: core's own (48h)." },
+  { key: "gateName", detail: "The gate's name. Default: `approve-<name>`." },
+  { key: "signalName", detail: "Deprecated spelling of `gateName` (#2202). Accepted through 0.59.0, removed in 0.60.0." },
+  { key: "gateTimeout", detail: "How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h)." },
   { key: "gateDescription", detail: "Override the gate description shown to the approver." },
   { key: "upgrade", detail: "`-upgrade` on the Init step: re-resolve provider and module versions." },
   { key: "cwd", detail: "Directory each step starts the `chant.config.*` search from." },
   { key: "compensate", detail: "Saga-style rollback on a failed apply: `true` with no command throws; supply `{ command }`." },
-  { key: "taskQueue", detail: "Override the task queue. Defaults to `name`." },
 ];
 
 /** `compensate`'s own shape when it is an object: `compensate: { <here> }`. */
@@ -71,7 +72,12 @@ export const PLAN_OPTS_KEYS: OptionKey[] = [
 
 /** `terraformApply(root, { <here> })`'s opts — `TerraformApplyArgs` minus `root`, plus step opts. */
 export const APPLY_OPTS_KEYS: OptionKey[] = [
-  { key: "planFile", detail: "The saved plan file to apply, relative to the root directory. Required." },
+  {
+    key: "planFile",
+    detail:
+      "The saved plan file to apply. Required on either kind of root; on a live root it is the approval " +
+      "artifact the apply re-plans against and refuses on a mismatch (choudoufu #878).",
+  },
   { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
   ...STEP_OPTS,
 ];

package/src/op/activities/choudoufu.acceptance.test.ts

@@ -0,0 +1,127 @@
+/**
+ * The acceptance test is choudoufu, not a fixture (#2103).
+ *
+ * Everything in `choudoufu.test.ts` proves the shape of the pure command
+ * builders and the activities' contract against a stubbed child process.
+ * This proves the shape runs against a real `choudoufu` binary: `live-check`
+ * against the `__fixtures__/live` root (no cloud calls, so this half needs
+ * only the binary), and `live-plan` against choudoufu's own pinned emulator
+ * (`live/smoke/README.md`'s `just smoke` docker compose stack in
+ * https://github.com/INTENTIUS/choudoufu), and that half makes real AWS SDK
+ * calls (the estate-wide marker sweep configures the AWS provider and reads
+ * it regardless of which resource types the root declares), so it needs the
+ * emulator's endpoint too.
+ *
+ * Both are gated, with the reason visible in the runner:
+ *
+ *   - no `choudoufu` on PATH: build it from
+ *     https://github.com/INTENTIUS/choudoufu with `go build ./cmd/choudoufu`
+ *     and put it on PATH, or download a release binary.
+ *   - `CHOUDOUFU_EMULATOR_ENDPOINT` unset: bring up the emulator with
+ *     `just smoke` in that checkout (it prints the floci container's mapped
+ *     port; `http://localhost:<port>` is this variable's value) and export
+ *     it before running this suite.
+ *
+ * Gating copied from `../../composites/terraform-apply-op.acceptance.test.ts`
+ * (`onPath`), which in turn copies `lexicons/k3s/src/serializer.acceptance.
+ * test.ts`'s pattern of skipping with the reason named in the describe title
+ * rather than failing when the real dependency is absent.
+ *
+ * `../../__fixtures__/ACCEPTANCE.md` records what this block has last passed
+ * against. The `live-plan` half was gated shut on choudoufu#894 until
+ * v0.14.0, which made the `-json` document reachable on a configuration that
+ * names its own estate and kept stdout to it (choudoufu PR 915); chant #2168
+ * dropped the gate and recorded the first run.
+ */
+
+import { execSync } from "node:child_process";
+import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { choudoufuLiveCheck, choudoufuLivePlan, terraformInit } from "./terraform";
+
+function onPath(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasChoudoufu = onPath("choudoufu");
+const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
+
+const skipReason = !hasChoudoufu
+  ? "no choudoufu binary on PATH"
+  : !emulatorEndpoint
+    ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
+    : "";
+
+const FIXTURE = join(import.meta.dirname, "..", "..", "__fixtures__", "live");
+const workspaces: string[] = [];
+
+afterAll(() => {
+  for (const dir of workspaces) rmSync(dir, { recursive: true, force: true });
+});
+
+/** A fresh copy of the live fixture, wired up with a real project config. */
+function project(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-choudoufu-accept-"));
+  workspaces.push(dir);
+  cpSync(FIXTURE, join(dir, "root"), { recursive: true });
+  writeFileSync(
+    join(dir, "chant.config.json"),
+    JSON.stringify(
+      { lexicons: ["terraform"], terraform: { binary: "choudoufu", roots: { estate: { dir: "./root" } } } },
+      null,
+      2,
+    ),
+  );
+  return dir;
+}
+
+describe.skipIf(skipReason !== "")(
+  `choudoufu live-check and live-plan against the fixture${skipReason ? ` (skipped: ${skipReason})` : ""}`,
+  () => {
+    it(
+      "live-check admits the __fixtures__/live root (null_resource, one live block, no cloud calls)",
+      { timeout: 60_000 },
+      async () => {
+        const dir = project();
+        const result = await choudoufuLiveCheck({ root: "estate", cwd: dir });
+        expect(result.refused).toBe(false);
+      },
+    );
+
+    it(
+      "live-plan reads the emulator and proposes creating both null_resources on a fresh estate",
+      { timeout: 300_000 },
+      async () => {
+        const dir = project();
+        const rootDir = join(dir, "root");
+
+        // The estate-wide marker sweep configures the AWS provider and reads
+        // it regardless of which resource types the root declares (#2103's
+        // ops.mdx and choudoufu's setup.md both name this), so the emulator's
+        // endpoint and dummy credentials have to reach the provider even
+        // though this fixture's only resource is `null_resource`.
+        process.env.AWS_ENDPOINT_URL ??= emulatorEndpoint;
+        process.env.AWS_ACCESS_KEY_ID ??= "choudoufu-emulator";
+        process.env.AWS_SECRET_ACCESS_KEY ??= "choudoufu-emulator";
+        process.env.AWS_DEFAULT_REGION ??= "us-east-1";
+
+        await terraformInit({ root: "estate", cwd: dir });
+
+        const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+        expect(result.estate).toBe("fixture-estate");
+        // A fresh estate proposes creating both null_resources: -detailed-
+        // exitcode's exit 2 (a plan with changes) is success here, not the
+        // no-drift case, since this root has never applied.
+        expect(result.drift).toBe(true);
+        expect(result.dir).toBe(rootDir);
+      },
+    );
+  },
+);