infraweaver 0.1.0

package/src/mcp/terraform/evidence.ts

@@ -0,0 +1,771 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { type } from "arktype";
+import { EVIDENCE_FILE, PRODUCT_NAME, TOOL_NAME } from "#app/brand";
+import {
+  type AssessmentScorecard,
+  type AssessWaiver,
+  runAssessmentPipeline,
+} from "#app/mcp/assess";
+import { CROSSWALK_DIGEST, type CrosswalkReport } from "#app/mcp/crosswalk";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { type EidasSeal, eidasSealFor } from "#app/mcp/terraform/eidas";
+import {
+  IDLE_FLOOR_ASSERTS,
+  IDLE_FLOOR_DOES_NOT_ASSERT,
+  type IdleFloorReport,
+} from "#app/mcp/terraform/idleFloor";
+import {
+  buildInTotoStatement,
+  keylessBundlePath,
+  keylessSigningPossible,
+  keylessSignStatement,
+} from "#app/mcp/terraform/keyless";
+import type { DriftEvidenceStatement } from "#app/mcp/terraform/planDrift";
+import {
+  collectWorkspaceProvenance,
+  type ModuleProvenance,
+} from "#app/mcp/terraform/refactor";
+import {
+  scanSessionOf,
+  upgradeStatementOf,
+} from "#app/mcp/terraform/scanSession";
+import {
+  loadSigningKey,
+  type SignatureMetadata,
+  signatureMetadata,
+  signBytes,
+} from "#app/mcp/terraform/signing";
+import { probedToolVersions } from "#app/mcp/terraform/toolchainIntegrity";
+import type { UpgradeEvidenceStatement } from "#app/mcp/terraform/transformPacks";
+import {
+  type Concern,
+  concernKeyOf,
+  type Severity,
+} from "#app/mcp/terraform/types";
+import {
+  VERIFICATION_STATUS_LABEL,
+  type VerificationStatus,
+  type VerificationSummary,
+} from "#app/mcp/terraform/verification";
+import { log } from "#app/utils/cli";
+import { githubContext } from "#app/utils/env";
+import packageJson from "#package.json" with { type: "json" };
+
+/**
+ * Backend-free compliance evidence bundle (the WS4a wedge — an auditor-facing
+ * artifact the OSS action can emit with **zero cloud and no backend**, committed
+ * to a `compliance/` path). It packages the read-only assessment — posture,
+ * per-control statements with their five-status verdict ([[verification]]), the
+ * crosswalk index, and the scanner coverage — into one deterministic JSON file.
+ *
+ * SCHEMA / HONESTY: this is Infraweaver's OWN structured schema, NOT OSCAL. A
+ * strict OSCAL (or compliance-trestle / C2P) emitter is a deliberate follow-up,
+ * gated on a buyer who actually needs OSCAL — emitting OSCAL nobody consumes is
+ * cost without value. The bundle is INDICATIVE alignment guidance, never an audit
+ * verdict, and it never claims `pass` for an unfired control (absence of a
+ * finding is not proof). Pure builder + a thin file-writing tool.
+ */
+
+// v0.2 was ADDITIVE over v0.1 (the `signature` field — Ed25519 signing metadata,
+// or an explicit null when no signing key is configured — see [[signing]]).
+// v0.3 is ADDITIVE over v0.2: each control statement gains `concern_key`, the
+// line-independent anchor (sha1(source|rule|file)) that stays stable across a fix
+// that shifts lines — the deep-link key a dashboard finding uses to locate its
+// entry in this bundle. Every prior field is unchanged, so older consumers parse.
+// v0.4 is ADDITIVE over v0.3: an optional `cost` block carrying the §5.19
+// credential-free IDLE FLOOR (what the configuration bills at zero traffic) with
+// its explicit asserts / does_not_assert pair. Present only when the cost tool
+// ran; every prior field is unchanged.
+// v0.6 is ADDITIVE over v0.5: an always-present `suppressions` block recording
+// what the posture EXCLUDES because a human accepted it (count, per-source
+// tally, never-expiring count, and every entry with its reason/expiry). The
+// human-readable report always listed waivers; the signed artifact did not, so
+// a repo with thirty active waivers signed identically to a clean one. Always
+// present — including `count: 0` — because an omitted section is ambiguous.
+// v0.7 is ADDITIVE over v0.6: an always-present `seal` block declaring the
+// eIDAS electronic-seal tier the `signature` reaches — today `simple` (or
+// `none` when unsigned), never `advanced`/`qualified`. Machine-readable rather
+// than prose, because "signed ed25519" is easy to over-read as a legal seal in
+// a procurement context and the difference is an Art. 35(2) presumption. The
+// qualified seal itself (§5.16: ASiC-E/CAdES-LTA + an Art. 41 timestamp from a
+// QTSP) is NOT built — it is blocked on trust-service onboarding, and this
+// block is the schema slot it lands in without a breaking change.
+// v0.5 was ADDITIVE over v0.4, two blocks:
+//   - `provenance` (always present) — WHO produced this evidence: the resolved
+//     model, the runtime, and the exact scanner versions the integrity gate
+//     observed before executing them (A.3 — the layer the Trivy compromise
+//     exploited; "evidence over trust" now covers the actor, not just the
+//     result).
+//   - `drift` (present only when detect_plan_drift ran) — the TC-2.1 statement:
+//     drift state, the `forgotten` blind-spot list, provider-noise filtering
+//     (auditable, field-by-field), and every coverage gap, each bound stated in
+//     the signed artifact itself.
+// v0.8 is ADDITIVE over v0.7, one block:
+//   - `upgrade` (present only when terraform_provider_upgrade matched a pack) —
+//     the TC-2.2 statement: which provider major boundary was crossed, which
+//     codified transforms the configuration contained, and the plan that backs
+//     it. Carries the pack's own non-exhaustiveness into the signed bytes so a
+//     reader cannot mistake the transform list for a complete migration.
+export const EVIDENCE_SCHEMA = "infraweaver-evidence/v0.8" as const;
+export const DEFAULT_EVIDENCE_PATH = `compliance/${EVIDENCE_FILE}`;
+
+export interface EvidenceControlStatement {
+  concern_id: string;
+  /** line-independent anchor (sha1(source|rule|file), see `concernKeyOf`) — the
+   * stable deep-link key into this bundle: a dashboard finding carries the same
+   * key, so its entry here is locatable even after a fix shifts line numbers.
+   * Absent when the backing concern wasn't supplied to the builder. */
+  concern_key?: string | undefined;
+  rule_id: string;
+  /** the five-status verdict for this statement (fail / not-code-verifiable). */
+  status: VerificationStatus;
+  severity?: string | undefined;
+  file?: string | undefined;
+  line?: number | null | undefined;
+  controls: { framework: string; control: string; title: string }[];
+}
+
+/**
+ * A refactor's evidence statement — emitted only for a refactor run. Carries the
+ * verdict, the equivalence sub-results that BACK it (when a keys-free proof ran),
+ * the adopted-module provenance, and — per §8 — BOTH what it asserts and what it
+ * explicitly does NOT. A `proposed-unproven` verdict (a b.4 third-party adoption
+ * shipped without a plan) asserts nothing about runtime behaviour.
+ */
+export interface EvidenceRefactorStatement {
+  verdict: "equivalence-proven" | "equivalence-failed" | "proposed-unproven";
+  equivalence?:
+    | {
+        resource_set_preserved: boolean;
+        arguments_preserved: boolean;
+        moves_exhaustive: boolean;
+        moves_detected: number;
+        uncovered_moves: number;
+        validate_passed: boolean;
+        fmt_clean: boolean;
+      }
+    | undefined;
+  /** every external module the config adopts, with its pinned version (provenance
+   * discipline — the analog to a SHA-pinned action). */
+  module_provenance: ModuleProvenance[];
+  /** true when the change is proposed but unproven — the unmissable b.4 marker. */
+  proposed_unproven: boolean;
+  asserts: string;
+  does_not_assert: string;
+}
+
+/**
+ * The §5.19 cost statement: the credential-free IDLE FLOOR — what this
+ * configuration bills at zero traffic — with the same asserts/does_not_assert
+ * honesty pair the refactor statement carries. Deliberately NOT a monthly total:
+ * usage-dependent lines are not derivable from Terraform, so the floor is the
+ * only cost figure this bundle is willing to sign.
+ */
+export interface EvidenceCostStatement {
+  /** Currency of every figure below (from the bundled price snapshot). */
+  currency: string;
+  /** Cloud region the list prices were captured for. */
+  region: string;
+  /** ISO date the bundled price snapshot was captured — makes staleness visible. */
+  priced_at: string;
+  /** Monthly cost that accrues at zero traffic. */
+  monthly_floor: number;
+  /** One entry per resource contributing to the floor. */
+  resources: {
+    address: string;
+    resource_type: string;
+    file: string;
+    line: number;
+    monthly_cost: number;
+  }[];
+  /** Catalogued resources left unpriced because their tier was not identifiable
+   *  — the signed floor is a lower bound by exactly these. */
+  unpriced: {
+    address: string;
+    resource_type: string;
+    file: string;
+    line: number;
+    reason: string;
+  }[];
+  asserts: string;
+  does_not_assert: string;
+}
+
+/**
+ * Build the suppression summary (pure). Unlike `cost` and `drift`, this block is
+ * **always present** — including with `count: 0`. An omitted section would be
+ * ambiguous ("nothing silenced" vs "this version didn't record it"), and the
+ * whole point is that a reader can tell a clean repo from a quiet one without
+ * having to trust that we'd have mentioned it.
+ */
+export function buildSuppressionSummary(
+  waivers: ReadonlyArray<AssessWaiver>,
+): EvidenceSuppressionSummary {
+  const by_source: Record<string, number> = {};
+  let never_expire = 0;
+  for (const w of waivers) {
+    by_source[w.source] = (by_source[w.source] ?? 0) + 1;
+    if (!w.expires) never_expire++;
+  }
+  return {
+    count: waivers.length,
+    by_source,
+    never_expire,
+    entries: waivers.map((w) => ({
+      rule_id: w.rule_id,
+      severity: w.severity,
+      file: w.file,
+      line: w.line,
+      reason: w.reason,
+      source: w.source,
+      expires: w.expires ?? null,
+    })),
+    asserts:
+      waivers.length === 0
+        ? "no finding was suppressed — the posture above covers everything the scanners reported."
+        : `${waivers.length} finding(s) were excluded from the posture above by an explicit, ` +
+          "reasoned suppression. Each is listed with its reason, source and expiry.",
+    does_not_assert:
+      "that a suppressed finding was fixed, or that its acceptance was correct — a waiver records " +
+      "a human decision, not a remediation. An expired waiver resurfaces the finding on the next " +
+      "run. An entry whose reason carries a `[via <tool> skip]` marker came from another scanner's " +
+      "own inline directive: honoured here, but neither authored nor reviewed here.",
+  };
+}
+
+/**
+ * Build the cost evidence statement (pure). Returns undefined when no cost
+ * analysis ran or nothing priced, so the bundle omits the section entirely
+ * rather than signing a zero that could be read as "this costs nothing".
+ */
+export function buildCostStatement(
+  report: IdleFloorReport | undefined,
+): EvidenceCostStatement | undefined {
+  if (!report || report.items.length === 0) return undefined;
+  return {
+    currency: report.currency,
+    region: report.region,
+    priced_at: report.priced_at,
+    monthly_floor: report.monthly_floor,
+    resources: report.items.map((i) => ({
+      address: i.address,
+      resource_type: i.resourceType,
+      file: i.file,
+      line: i.line,
+      monthly_cost: i.monthly_cost,
+    })),
+    /** Catalogued resources left unpriced because their tier was not
+     *  identifiable — the signed floor is a lower bound by exactly these. */
+    unpriced: report.unpriced.map((u) => ({
+      address: u.address,
+      resource_type: u.resourceType,
+      file: u.file,
+      line: u.line,
+      reason: u.reason,
+    })),
+    asserts: IDLE_FLOOR_ASSERTS,
+    does_not_assert: IDLE_FLOOR_DOES_NOT_ASSERT,
+  };
+}
+
+/** the equivalence sub-results buildRefactorStatement reads (the shape recorded
+ * in `scanSession.refactorEquivalence`). */
+export interface RefactorEquivalenceInput {
+  equivalent: boolean;
+  resource_set_equivalent: boolean;
+  arg_names_equivalent: boolean;
+  moves_exhaustive: boolean;
+  moves_detected: number;
+  validate_passed: boolean;
+  fmt_clean: boolean;
+  uncovered_moves: { from: string; to: string }[];
+}
+
+/**
+ * Build the refactor evidence statement (pure). Returns undefined when nothing
+ * refactor-related happened (no equivalence proof, not a proposed-unproven b.4,
+ * no external module) so the bundle omits the section entirely. Infraweaver asserts
+ * only what the inputs prove — a failed or absent proof asserts nothing.
+ */
+export function buildRefactorStatement(args: {
+  equivalence?: RefactorEquivalenceInput | undefined;
+  provenance: ModuleProvenance[];
+  proposedUnproven: boolean;
+}): EvidenceRefactorStatement | undefined {
+  const { equivalence, provenance, proposedUnproven } = args;
+  if (!equivalence && !proposedUnproven && provenance.length === 0)
+    return undefined;
+
+  let verdict: EvidenceRefactorStatement["verdict"];
+  let asserts: string;
+  let doesNotAssert: string;
+  if (equivalence?.equivalent) {
+    verdict = "equivalence-proven";
+    asserts =
+      "structure changed, behaviour preserved — same resource set, identical arguments, every relocation covered by a `moved {}` block, terraform validate + fmt clean.";
+    doesNotAssert =
+      "that unrelated resources are correct or the configuration is otherwise optimal; completeness is never claimed.";
+  } else if (equivalence) {
+    verdict = "equivalence-failed";
+    asserts =
+      "nothing — the equivalence proof did NOT pass, so this change must not be treated as behaviour-preserving.";
+    doesNotAssert =
+      "behaviour-equivalence (the proof failed; see the run reasons).";
+  } else {
+    // proposed-unproven b.4 (or provenance recorded with no proof context).
+    verdict = "proposed-unproven";
+    asserts =
+      "nothing about runtime behaviour — this third-party-module adoption is PROPOSED only and was not verified against a plan.";
+    doesNotAssert =
+      "behaviour-equivalence (it alters behaviour and is not claimed equivalent); no terraform plan was run.";
+  }
+
+  return {
+    verdict,
+    equivalence: equivalence
+      ? {
+          resource_set_preserved: equivalence.resource_set_equivalent,
+          arguments_preserved: equivalence.arg_names_equivalent,
+          moves_exhaustive: equivalence.moves_exhaustive,
+          moves_detected: equivalence.moves_detected,
+          uncovered_moves: equivalence.uncovered_moves.length,
+          validate_passed: equivalence.validate_passed,
+          fmt_clean: equivalence.fmt_clean,
+        }
+      : undefined,
+    module_provenance: provenance,
+    proposed_unproven: verdict === "proposed-unproven",
+    asserts,
+    does_not_assert: doesNotAssert,
+  };
+}
+
+/**
+ * What this run did NOT judge, because a human had already accepted it.
+ *
+ * WHY THIS IS IN THE SIGNED BYTES. `posture` and `control_statements` describe
+ * the OPEN findings only — suppressed ones are excluded by design, because a
+ * waived finding genuinely is an accepted risk. But that means a repo with
+ * thirty active waivers produced a bundle byte-indistinguishable from a
+ * genuinely clean one, and the difference is exactly what an assessor is there
+ * to examine. The human-readable report has always listed waivers; the SIGNED
+ * artifact did not, which made the signature cover the flattering half of the
+ * story.
+ *
+ * Each entry is what was silenced, where it is, why (a reason is mandatory
+ * everywhere), by which mechanism, and until when.
+ *
+ * A note on `source`. It records the two things the suppression pipeline
+ * actually models: `inline` (a directive in the source file) and `policy` (the
+ * `.infraweaver.yml` block). A skip written for ANOTHER scanner
+ * (`# checkov:skip=…`) is honoured and lands under `inline`, with the pipeline's
+ * own `[via <tool> skip]` marker appended to its reason — so the distinction is
+ * visible in the entry without this block claiming a structured tally the
+ * concern model does not carry.
+ */
+export interface EvidenceSuppressionRecord {
+  rule_id: string;
+  severity: string;
+  file: string;
+  line?: number | null | undefined;
+  /** mandatory everywhere; carries the `[via <tool> skip]` marker when the
+   *  directive was another scanner's rather than ours. */
+  reason: string;
+  /** `inline` = a directive in the source file; `policy` = the `.infraweaver.yml` block. */
+  source: string;
+  /** ISO date the waiver lapses, or null for an open-ended one. */
+  expires: string | null;
+}
+
+export interface EvidenceSuppressionSummary {
+  /** how many findings this bundle's posture excludes. 0 ⇒ nothing silenced. */
+  count: number;
+  /** count by mechanism (`inline` / `policy`) — how the silencing was applied. */
+  by_source: Record<string, number>;
+  /** open-ended waivers — the ones with no review date. */
+  never_expire: number;
+  entries: EvidenceSuppressionRecord[];
+  asserts: string;
+  does_not_assert: string;
+}
+
+/**
+ * WHO produced this evidence (A.3). The bundle always named the engine; after
+ * the Trivy compromise that is not enough — a poisoned scanner produces
+ * poisoned findings under a clean engine version. This block records the whole
+ * acting chain: the model that drove the agent, the runtime, and the exact
+ * scanner builds the integrity gate observed (`toolchainIntegrity`) before
+ * executing them. Nothing here is fabricated: a tool that never ran this
+ * session is simply absent from `scanners`, and an unresolved model is null.
+ */
+export interface EvidenceProvenance {
+  /** resolved model specifier that drove the agent, or null (auto/unknown —
+   * e.g. a local `infraweaver mcp` session has no agent of its own). */
+  model: string | null;
+  /** the Node.js runtime the engine executed on (`process.version`). */
+  node: string;
+  /** exact scanner versions probed by the integrity gate before execution —
+   * only tools that actually ran this session appear. */
+  scanners: { tool: string; version: string | null }[];
+}
+
+export interface EvidenceBundle {
+  /** Infraweaver's own schema id — explicitly NOT OSCAL (see module note). */
+  schema: typeof EVIDENCE_SCHEMA;
+  /** caller-supplied ISO timestamp (kept out of the builder so it stays pure). */
+  generated_at: string;
+  tool: { name: typeof TOOL_NAME; version: string };
+  /** who produced this evidence — model + runtime + observed scanner builds. */
+  provenance: EvidenceProvenance;
+  subject: {
+    scanned_dir: string;
+    repo?: string | undefined;
+    ref?: string | undefined;
+    commit?: string | undefined;
+  };
+  posture: AssessmentScorecard["posture"];
+  summary: {
+    total: number;
+    by_severity: AssessmentScorecard["by_severity"];
+    verification: VerificationSummary["counts"];
+  };
+  /** one statement per mapped concern, each carrying its status + controls. */
+  control_statements: EvidenceControlStatement[];
+  /** which scanners code-verified vs which were inconclusive (coverage gaps). */
+  coverage: VerificationSummary["coverage"];
+  /** what the posture above EXCLUDES because a human accepted it. Always
+   * present (0 when nothing was silenced) so a clean repo and a quiet one are
+   * distinguishable from the signed bytes alone. */
+  suppressions: EvidenceSuppressionSummary;
+  crosswalk: {
+    version: string;
+    reviewed: string;
+    /** sha256 of the reviewed crosswalk tables that produced these verdicts —
+     *  binds the exact (integrity-gated) control mapping into the signed bundle. */
+    digest: string;
+    by_framework: CrosswalkReport["by_framework"];
+  };
+  /** the five-status legend, so the bundle is self-describing for an assessor. */
+  legend: Record<VerificationStatus, string>;
+  /** present only on a refactor run — the equivalence/proposed-unproven statement
+   * with the proof that backs it (omitted entirely otherwise). */
+  refactor?: EvidenceRefactorStatement | undefined;
+  /** present only when the credential-free cost analysis ran — the §5.19 idle
+   * floor (what this bills at zero traffic), never a monthly total. */
+  cost?: EvidenceCostStatement | undefined;
+  /** present only when detect_plan_drift ran — the TC-2.1 drift statement:
+   * signed, bounded proof of whether live infrastructure matched the committed
+   * configuration when the plan artifact was produced, with the `forgotten`
+   * blind-spot list and every coverage gap carried in the claim itself. */
+  drift?: DriftEvidenceStatement | undefined;
+  /** present only when a provider-major upgrade was detected (TC-2.2) — which
+   * boundary was crossed, the codified transforms found in this configuration,
+   * and the plan that proves (or fails to prove) the result. A `no-plan` verdict
+   * is recorded rather than omitted: an upgrade shipped without a plan is
+   * exactly the thing a reader must be able to see. */
+  upgrade?: UpgradeEvidenceStatement | undefined;
+  /** Ed25519 signing metadata (public key + fingerprint + the sibling `.sig`
+   * carrying the detached signature over this file's exact bytes), or an
+   * explicit null when no INFRAWEAVER_SIGNING_KEY is configured — never fake. */
+  signature: SignatureMetadata | null;
+  /** §5.16 always-present eIDAS assurance declaration: which electronic-seal
+   * tier the `signature` above actually reaches, and — the load-bearing half —
+   * which it does not. `signature` says HOW the bytes were signed; this says
+   * WHAT THAT IS WORTH legally, so a reader cannot over-read an Ed25519
+   * signature as a qualified seal. Present even when unsigned (`level: "none"`),
+   * because an omitted section is ambiguous. See [[eidas]]. */
+  seal: EidasSeal;
+  disclaimer: string;
+}
+
+const DISCLAIMER =
+  "Indicative alignment guidance from a deterministic starter rule-pack — NOT an " +
+  "audit verdict. Statuses are code-verified only; an inconclusive check is a " +
+  "coverage gap (not a pass) and absence of a finding is not proof of compliance.";
+
+export interface EvidenceSubject {
+  scanned_dir: string;
+  repo?: string | undefined;
+  ref?: string | undefined;
+  commit?: string | undefined;
+}
+
+/**
+ * Build the evidence bundle from an assessment's scorecard + crosswalk. Pure —
+ * `generatedAt` and the subject identifiers are passed in so the same inputs
+ * always produce the same bytes (and tests don't need a clock). Control
+ * statements come from the crosswalk entries (which already carry the
+ * verification status), enriched with the concern's severity/location when the
+ * scanned concerns are supplied (the crosswalk entry itself carries neither).
+ */
+export function buildEvidenceBundle(args: {
+  scorecard: AssessmentScorecard;
+  crosswalk: CrosswalkReport;
+  subject: EvidenceSubject;
+  generatedAt: string;
+  version?: string;
+  /** the scanned concerns backing the crosswalk entries — the source of each
+   * statement's severity/file/line enrichment. */
+  concerns?: Concern[];
+  refactor?: EvidenceRefactorStatement | undefined;
+  /** the §5.19 idle-floor statement; omitted when no cost analysis ran. */
+  cost?: EvidenceCostStatement | undefined;
+  /** the TC-2.1 drift statement; omitted when detect_plan_drift didn't run. */
+  drift?: DriftEvidenceStatement | undefined;
+  /** the TC-2.2 upgrade statement; omitted when no provider-major pack applied. */
+  upgrade?: UpgradeEvidenceStatement | undefined;
+  /** who produced this evidence (A.3). REQUIRED — an evidence bundle that
+   * doesn't name its actor is the gap this block exists to close. Callers pass
+   * real values (the builder stays pure; no ambient reads here). */
+  provenance: EvidenceProvenance;
+  /** signing metadata when a key is configured; omitted/null ⇒ explicit
+   * `"signature": null` (the honest-unsigned marker). */
+  signature?: SignatureMetadata | null;
+}): EvidenceBundle {
+  const {
+    scorecard,
+    crosswalk,
+    subject,
+    generatedAt,
+    refactor,
+    cost,
+    drift,
+    upgrade,
+  } = args;
+  const concernById = new Map((args.concerns ?? []).map((c) => [c.id, c]));
+  const control_statements: EvidenceControlStatement[] = crosswalk.entries.map(
+    (e) => {
+      const concern = concernById.get(e.concern_id);
+      return {
+        concern_id: e.concern_id,
+        rule_id: e.rule_id,
+        status: e.status,
+        ...(concern
+          ? {
+              concern_key: concernKeyOf(concern),
+              severity: concern.severity,
+              file: concern.location.file,
+              line: concern.location.line,
+            }
+          : {}),
+        controls: e.controls,
+      };
+    },
+  );
+  return {
+    schema: EVIDENCE_SCHEMA,
+    generated_at: generatedAt,
+    tool: { name: TOOL_NAME, version: args.version ?? packageJson.version },
+    provenance: args.provenance,
+    subject,
+    posture: scorecard.posture,
+    summary: {
+      total: scorecard.total,
+      by_severity: scorecard.by_severity,
+      verification: scorecard.verification.counts,
+    },
+    control_statements,
+    coverage: scorecard.verification.coverage,
+    // Derived from the scorecard the report already renders, so the signed
+    // bundle and the human-readable report can never disagree about what was
+    // silenced.
+    suppressions: buildSuppressionSummary(scorecard.waivers),
+    crosswalk: {
+      version: crosswalk.version,
+      reviewed: crosswalk.reviewed,
+      digest: CROSSWALK_DIGEST,
+      by_framework: crosswalk.by_framework,
+    },
+    legend: VERIFICATION_STATUS_LABEL,
+    ...(refactor ? { refactor } : {}),
+    ...(cost ? { cost } : {}),
+    ...(drift ? { drift } : {}),
+    ...(upgrade ? { upgrade } : {}),
+    signature: args.signature ?? null,
+    // Derived from the signature actually present, never from configuration, so
+    // the declared level can't drift from what the bundle really carries.
+    seal: eidasSealFor(args.signature ?? null),
+    disclaimer: DISCLAIMER,
+  };
+}
+
+export const TerraformEmitEvidenceParams = type({
+  "output_path?": type.string.describe(
+    `where to write the evidence bundle (default: ./${DEFAULT_EVIDENCE_PATH} in the workspace). Commit it so the compliance/ path is the auditable evidence trail.`,
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to include (default: the run's configured threshold, else low).",
+  ),
+  "proposed_unproven?": type("boolean").describe(
+    "refactor b.4 only: set true when emitting evidence for a third-party-module adoption shipped WITHOUT a plan, so the bundle records the unmissable `proposed — unproven` marker (it asserts nothing about runtime behaviour). Ignored when a keys-free equivalence proof was already recorded this run.",
+  ),
+});
+
+export function TerraformEmitEvidenceTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_emit_evidence",
+    description:
+      "Emit a backend-free compliance EVIDENCE BUNDLE (auditor-facing JSON) for the workspace — the wedge that " +
+      "produces assessor-ready evidence with no cloud and no backend. Runs the read-only assessment and writes " +
+      `a deterministic bundle (default \`${DEFAULT_EVIDENCE_PATH}\`): overall \`posture\`, per-control ` +
+      "statements each with a five-status verdict (fail / not-code-verifiable), the scanner `coverage` " +
+      "(verified vs inconclusive), and the indicative crosswalk index. Commit the file so `compliance/` is the " +
+      `auditable trail. It NEVER modifies Terraform or opens a PR. The schema is ${PRODUCT_NAME}'s own (not OSCAL); ` +
+      "the bundle is indicative alignment guidance, never an audit verdict, and never claims a pass it can't " +
+      "code-verify. Pairs with `terraform_assess` (the human-readable report) and `terraform_emit_sarif`.",
+    parameters: TerraformEmitEvidenceParams,
+    execute: execute(
+      async ({ output_path, severity_threshold, proposed_unproven }) => {
+        const configured = ctx.payload.severityThreshold as
+          | Severity
+          | undefined;
+        const threshold: Severity = severity_threshold ?? configured ?? "low";
+        const { cwd, open, scorecard, crosswalk } = runAssessmentPipeline(
+          ctx,
+          threshold,
+        );
+
+        // refactor statement (omitted on a non-refactor run): the recorded keys-free
+        // equivalence proof + adopted-module provenance + the proposed-unproven marker.
+        const session = scanSessionOf(ctx.toolState);
+        const refactor = buildRefactorStatement({
+          equivalence: session.refactorEquivalence,
+          provenance: collectWorkspaceProvenance(cwd),
+          proposedUnproven: proposed_unproven ?? false,
+        });
+        // surface the proposed-unproven verdict to the Cloud report (cloudReport.ts):
+        // an equivalence proof, when present, takes precedence, so only record the
+        // flag when the statement actually resolved to proposed-unproven.
+        if (refactor?.proposed_unproven)
+          session.refactorProposedUnproven = true;
+        // cost statement (omitted unless terraform_emit_cost ran): the SAME idle-floor
+        // numbers cost.md shows, so the artifact and the signed bundle can't disagree.
+        const cost = buildCostStatement(session.lastIdleFloor);
+        // drift statement (omitted unless detect_plan_drift ran): drift — with the
+        // forgotten blind-spot list and any coverage gap — enters the SIGNED bundle
+        // instead of dying as a run verdict (TC-2.1).
+        const drift = session.lastDrift;
+        // upgrade statement (TC-2.2; omitted unless terraform_provider_upgrade
+        // matched a pack): binds the detected transforms to the plan that came
+        // after them. The plan facts are read from the session rather than taken
+        // from the agent, so a "proven" verdict cannot be self-reported. A run with
+        // no plan becomes the `no-plan` verdict rather than a silent omission.
+        const upgrade = upgradeStatementOf(session);
+
+        // SECURITY: confine the agent-supplied path to the workspace (same guard as
+        // terraform_emit_sarif) so it can't clobber arbitrary files on the runner.
+        const target = resolveWithinCwd(
+          cwd,
+          output_path ?? DEFAULT_EVIDENCE_PATH,
+        );
+        // Ed25519 signing (opt-in via INFRAWEAVER_SIGNING_KEY). A set-but-malformed
+        // key throws here — a configured signer must never silently emit unsigned.
+        const signingKey = loadSigningKey();
+        const sigPath = `${target}.sig`;
+        const gh = githubContext();
+        const bundle = buildEvidenceBundle({
+          scorecard,
+          crosswalk,
+          concerns: open,
+          subject: {
+            scanned_dir: cwd,
+            repo: gh.repository,
+            ref: gh.refName,
+            commit: gh.sha,
+          },
+          generatedAt: new Date().toISOString(),
+          refactor,
+          cost,
+          drift,
+          upgrade,
+          // WHO produced this evidence (A.3): the resolved model (absent on a
+          // local MCP session), the runtime, and the exact scanner builds the
+          // integrity gate observed before executing them this session.
+          provenance: {
+            model: ctx.resolvedModel ?? null,
+            node: process.version,
+            scanners: probedToolVersions(),
+          },
+          signature: signingKey
+            ? signatureMetadata(signingKey, basename(sigPath))
+            : null,
+        });
+        const bytes = `${JSON.stringify(bundle, null, 2)}\n`;
+        // the default compliance/ dir may not exist yet on a first run.
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, bytes);
+        // detached signature over the EXACT bytes written (builder is deterministic,
+        // so no canonicaliser) — verify with `infraweaver verify-evidence`.
+        if (signingKey)
+          writeFileSync(sigPath, `${signBytes(bytes, signingKey)}\n`);
+
+        // Second tier: keyless Sigstore attestation (opt-in via INFRAWEAVER_KEYLESS_SIGNING,
+        // CI-only). Best-effort — a Fulcio/Rekor failure logs and leaves the evidence
+        // (+ Ed25519 sig) intact rather than aborting the emit. The in-toto statement's
+        // subject is this file (by sha256 digest), so the attestation binds the exact
+        // bytes to the workflow's OIDC identity, auditable in the public Rekor log.
+        let keylessBundleFile: string | undefined;
+        if (keylessSigningPossible()) {
+          try {
+            const statement = buildInTotoStatement({
+              subjectName: basename(target),
+              artifactBytes: bytes,
+              predicate: {
+                posture: bundle.posture,
+                control_statements: bundle.control_statements.length,
+                verification: bundle.summary.verification,
+                tool: bundle.tool,
+                generated_at: bundle.generated_at,
+                subject: bundle.subject,
+              },
+            });
+            const sigstoreBundle = await keylessSignStatement(statement);
+            keylessBundleFile = keylessBundlePath(target);
+            writeFileSync(
+              keylessBundleFile,
+              `${JSON.stringify(sigstoreBundle, null, 2)}\n`,
+            );
+            log.info(
+              `» terraform_emit_evidence: keyless Sigstore attestation → ${keylessBundleFile}`,
+            );
+          } catch (e) {
+            log.warning(
+              `» terraform_emit_evidence: keyless signing failed (evidence still emitted): ${e instanceof Error ? e.message : String(e)}`,
+            );
+          }
+        }
+        log.info(
+          `» terraform_emit_evidence: ${scorecard.posture} — ${bundle.control_statements.length} control statement(s) → ${target}` +
+            (signingKey
+              ? ` (signed ed25519, key ${signingKey.fingerprint.slice(0, 16)}…)`
+              : " (unsigned — no INFRAWEAVER_SIGNING_KEY)"),
+        );
+        return toolOk({
+          output_path: target,
+          posture: bundle.posture,
+          statements: bundle.control_statements.length,
+          verification: bundle.summary.verification,
+          ...(bundle.refactor
+            ? { refactor_verdict: bundle.refactor.verdict }
+            : {}),
+          signed: signingKey !== null,
+          ...(signingKey
+            ? {
+                signature_path: sigPath,
+                key_fingerprint_sha256: signingKey.fingerprint,
+              }
+            : {}),
+          keyless_signed: keylessBundleFile !== undefined,
+          ...(keylessBundleFile
+            ? { keyless_bundle_path: keylessBundleFile }
+            : {}),
+        });
+      },
+    ),
+  });
+}