infraweaver 0.1.0

package/src/utils/cli.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI utilities
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+// re-export logging utilities for backward compatibility
+export {
+  formatIndentedField,
+  formatJsonValue,
+  formatUsageSummary,
+  log,
+  writeSummary,
+} from "#app/utils/log";
+
+/**
+ * Finds a CLI executable path by checking if it's installed globally
+ * @param name The name of the CLI executable to find
+ * @returns The path to the CLI executable, or null if not found
+ */
+export function findCliPath(name: string): string | null {
+  // `which` is POSIX-only. The action always runs on Linux, but this repo is
+  // developed on Windows, where `which` does not exist and the lookup fails
+  // silently as "not installed" — use `where` there. `where` can print several
+  // matches, one per line, so take the first.
+  const isWindows = process.platform === "win32";
+  const result = spawnSync(isWindows ? "where" : "which", [name], { encoding: "utf-8" });
+  if (result.status === 0 && result.stdout) {
+    const cliPath = result.stdout.split(/\r?\n/)[0]?.trim();
+    if (cliPath && existsSync(cliPath)) {
+      return cliPath;
+    }
+  }
+  return null;
+}

package/src/utils/cloudClient.ts

@@ -0,0 +1,57 @@
+import { type ApiFetchOptions, apiFetch } from "#app/utils/apiFetch";
+import { DEFAULT_CLOUD_TIMEOUT_MS } from "#app/utils/cloudFetchCore";
+
+/**
+ * Thin typed seam over `apiFetch` for the Infraweaver Cloud routes.
+ *
+ * Consumers previously hand-built each request: the `Authorization: Bearer`
+ * header (with `Authorization`/`authorization` casing drift), JSON serialization
+ * + content-type, and the timeout were re-inlined at every call site. This owns
+ * those three pieces once and returns the raw `Response`, so each caller keeps
+ * its own status/JSON/retry handling.
+ *
+ * The stdlib-only post hook (`entryPost.ts`) intentionally does NOT use this —
+ * it calls `cloudFetchCore` directly to stay free of node_modules imports.
+ */
+
+/** The one home for the bearer header — the org JWT (`apiToken`), a GitHub App
+ *  installation token, or an OIDC id-token, depending on the route. */
+export function bearer(credential: string): { Authorization: string } {
+  return { Authorization: `Bearer ${credential}` };
+}
+
+export type CloudRequest = {
+  path: string;
+  method?: string | undefined;
+  /** bearer token for the `Authorization` header; omit for an unauthenticated call. */
+  credential?: string | undefined;
+  /** extra headers beyond `Authorization` (e.g. `X-GitHub-OIDC-Token`). */
+  headers?: Record<string, string> | undefined;
+  /** a JSON body — serialized here, with `content-type: application/json` set. */
+  json?: unknown;
+  /** a pre-serialized body (used when the body is not JSON). */
+  body?: string | undefined;
+  /** request timeout in ms; defaults to the shared cloud ceiling. */
+  timeoutMs?: number | undefined;
+};
+
+/** Issue an authenticated Cloud API request; returns the raw `Response`. */
+export async function cloudRequest(req: CloudRequest): Promise<Response> {
+  const headers: Record<string, string> = { ...req.headers };
+  if (req.credential) Object.assign(headers, bearer(req.credential));
+
+  let body = req.body;
+  if (req.json !== undefined) {
+    body = JSON.stringify(req.json);
+    headers["content-type"] = "application/json";
+  }
+
+  const options: ApiFetchOptions = {
+    path: req.path,
+    method: req.method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(req.timeoutMs ?? DEFAULT_CLOUD_TIMEOUT_MS),
+  };
+  return apiFetch(options);
+}

package/src/utils/cloudFetchCore.ts

@@ -0,0 +1,139 @@
+/**
+ * stdlib-only Infraweaver API fetch core (no node_modules) — shared by
+ * `apiFetch` (the main runtime wrapper) and `entryPost.ts` (the GHA `post:`
+ * hook, which runs directly from the action checkout without node_modules;
+ * see entryPost.stdlibOnly.test.ts). Owns everything the two callers
+ * previously kept in lockstep by hand: the default API host, the
+ * bearer-credential host allowlist, the Vercel bypass secret, and the
+ * default request timeout.
+ */
+
+import { DEFAULT_API_URL, PRIMARY_DOMAIN } from "#app/brand";
+
+export { DEFAULT_API_URL };
+
+/**
+ * Ceiling for Cloud API calls that don't bring their own AbortSignal — a
+ * stalled backend must never hang the action (or its post hook) indefinitely.
+ * Callers with tighter or looser needs pass an explicit `signal`.
+ */
+export const DEFAULT_CLOUD_TIMEOUT_MS = 30_000;
+
+function isLocalUrl(url: URL): boolean {
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1";
+}
+
+/**
+ * Operator-pinned extra hosts (comma-separated, exact hostnames) for a
+ * self-hosted / alternate Cloud deployment — e.g. a Railway or custom-domain
+ * backend that isn't under `*.infraweaver.dev`. This preserves the security
+ * property: the operator must *explicitly name the exact host* in
+ * `API_ALLOWED_HOSTS` before any bearer credential is sent there; it only widens
+ * the allowlist for hosts the operator already controls and configured.
+ */
+function configuredAllowedHosts(): string[] {
+  return (process.env.API_ALLOWED_HOSTS ?? "")
+    .split(",")
+    .map((h) => h.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+// The Infraweaver JWT (apiToken) and codex write-back secret travel as
+// `Authorization: Bearer` to this host. Pin it to a known allowlist so a
+// misconfigured/hostile `API_URL` can't redirect those bearer credentials to
+// an attacker-controlled host (https alone is not enough — it must be the right
+// host). localhost stays exempt for local dev; self-hosted deployments add their
+// exact host via `API_ALLOWED_HOSTS`.
+function isAllowedApiHost(url: URL): boolean {
+  if (isLocalUrl(url)) return true;
+  const host = url.hostname.toLowerCase();
+  if (host === PRIMARY_DOMAIN || host.endsWith(`.${PRIMARY_DOMAIN}`))
+    return true;
+  return configuredAllowedHosts().includes(host);
+}
+
+/**
+ * resolve the Infraweaver API base URL.
+ *
+ * in the action: API_URL is not explicitly set, so this falls back to
+ * DEFAULT_API_URL. in local dev: API_URL=http://localhost:3000 (from .env).
+ *
+ * enforces https:// for non-local URLs to prevent cleartext credential
+ * transmission.
+ */
+export function resolveApiUrl(): string {
+  const raw = process.env.API_URL || DEFAULT_API_URL;
+  const parsed = new URL(raw);
+
+  if (parsed.protocol !== "https:" && !isLocalUrl(parsed)) {
+    throw new Error(
+      `API_URL must use https:// (got ${parsed.protocol}). only localhost is exempt.`,
+    );
+  }
+
+  if (!isAllowedApiHost(parsed)) {
+    throw new Error(
+      `API_URL host '${parsed.hostname}' is not allowed. ` +
+        `Bearer credentials are only sent to ${PRIMARY_DOMAIN} (or a *.${PRIMARY_DOMAIN} host), localhost, ` +
+        `or a host you explicitly pin in API_ALLOWED_HOSTS.`,
+    );
+  }
+
+  return raw;
+}
+
+export type CloudFetchOptions = {
+  path: string;
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: string | undefined;
+  signal?: AbortSignal | undefined;
+};
+
+/**
+ * fetch against the Infraweaver API with Vercel deployment protection bypass.
+ *
+ * adds the bypass secret as BOTH a query parameter and a header for maximum
+ * reliability. the server-side forwarding code uses query params, and the
+ * Vercel docs say both work, so we do both as belt-and-suspenders.
+ */
+export async function cloudFetch(
+  options: CloudFetchOptions,
+): Promise<Response> {
+  const url = new URL(options.path, resolveApiUrl());
+
+  const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+  if (bypassSecret) {
+    url.searchParams.set("x-vercel-protection-bypass", bypassSecret);
+  }
+
+  const headers: Record<string, string> = {
+    ...options.headers,
+  };
+
+  // also add as header for belt-and-suspenders
+  if (bypassSecret) {
+    headers["x-vercel-protection-bypass"] = bypassSecret;
+  }
+
+  // never send Content-Type on body-less requests. empirically, Vercel's
+  // Next.js lambda adapter (Next 16.1.x) throws `SyntaxError: Unexpected
+  // end of data` before delegating to the route handler — returning a 500 —
+  // when Content-Type is set but no body is present. exact mechanism is
+  // unverified (minified runtime frame), but Content-Type on a body-less
+  // request has no defined semantics per RFC 9110 §8.3 anyway. see #692.
+  if (!options.body) {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === "content-type") delete headers[key];
+    }
+  }
+
+  const init: RequestInit = {
+    method: options.method ?? "GET",
+    headers,
+    signal: options.signal ?? AbortSignal.timeout(DEFAULT_CLOUD_TIMEOUT_MS),
+  };
+  if (options.body) init.body = options.body;
+
+  return fetch(url.toString(), init);
+}

package/src/utils/cloudReport.ts

@@ -0,0 +1,316 @@
+import * as core from "@actions/core";
+import { PRODUCT_NAME } from "#app/brand";
+import { CROSSWALK_VERSION, packControlsForConcern } from "#app/mcp/crosswalk";
+import { cyberEssentialsScore } from "#app/mcp/cyberEssentials";
+import { ruleDocUrl } from "#app/mcp/terraform/decisions";
+import { dedupeCaptures } from "#app/mcp/terraform/fixMemory";
+import { riskScore } from "#app/mcp/terraform/risk";
+import {
+  scanSessionOf,
+  upgradeStatementOf,
+} from "#app/mcp/terraform/scanSession";
+import { captureProvenTransforms } from "#app/mcp/terraform/transformPacks";
+import { type Concern, concernKeyOf } from "#app/mcp/terraform/types";
+
+// The CE score is computed in the shared `cyberEssentials` module so the Assess
+// report and this Cloud report report the identical number; re-exported here to
+// keep this module's existing public surface (and the report test) intact.
+export { cyberEssentialsScore } from "#app/mcp/cyberEssentials";
+
+import type { ToolState } from "#app/toolState";
+import { cloudOidcAudience, isBackendConfigured } from "#app/utils/apiUrl";
+import { log } from "#app/utils/cli";
+import { cloudRequest } from "#app/utils/cloudClient";
+
+// The OIDC audience the tokenless path requests; resolved via `cloudOidcAudience()` so it
+// matches the Cloud's `expectedOidcAudience()` and stays operator-overridable from a
+// single place. Re-exported to preserve this module's public surface.
+export { cloudOidcAudience };
+
+/**
+ * Resolve the credential to authenticate the Cloud report with, in order of
+ * preference:
+ *   1. An explicit `tmnd_` org token (the `api_token` input).
+ *   2. A GitHub Actions OIDC token — the tokenless GitHub App path. Requires
+ *      `permissions: id-token: write`; the App installation is the consent gate
+ *      Cloud checks. Returns undefined when neither is available (pure OSS run).
+ */
+export async function resolveCloudCredential(
+  apiToken: string | undefined,
+): Promise<string | undefined> {
+  if (apiToken) return apiToken;
+  try {
+    const oidc = await core.getIDToken(cloudOidcAudience());
+    return oidc || undefined;
+  } catch {
+    // No `id-token: write` permission, or not running in GitHub Actions — the
+    // run stays pure OSS and reports nothing.
+    return undefined;
+  }
+}
+
+/**
+ * Ingest seam — POST a finished run's findings/posture to Infraweaver Cloud
+ * so the dashboard reflects this repo. This is the explicit ORG-TOKEN path: the
+ * caller passes the `tmnd_` token (the `api_token` input); the tokenless GitHub
+ * App path reports differently and standalone OSS runs don't report at all.
+ *
+ * The wire shape matches infraweaver-ui `reportSchema`
+ * (src/features/api/schemas.ts) — kept in sync by hand across the action ⇄ cloud
+ * JSON boundary (the two codebases can't share types).
+ */
+
+export type CloudPosture = "clean" | "advisory" | "action-required";
+
+// The Cloud `run_mode` enum. The engine's mode NAME is title-cased ("Remediate"),
+// so it must be lowered to the enum value or the server's run insert rejects it.
+// NOTE: "generate" was removed with infra-generation (2026-06-22) — the engine can no
+// longer select that mode, so it's dropped here too. "review" stays: the generic
+// PR-review surface is still reachable (IncrementalReview / select_mode). "refactor"
+// is the behaviour-preserving modularise verb (its proof rides in run.refactor below).
+// The 2026-06-27 CI verbs (PolicyGate/UpdateDependencies/ModernizeDeprecated/
+// CostOptimization) and the read-only posture verbs DriftDetect/ComplianceAudit
+// lower 1:1 onto matching Cloud enum values — apply the Cloud run_mode enum +
+// reportSchema additions BEFORE deploying this, or the run insert rejects.
+// (TerraformCodeReview is intentionally absent: like IncrementalReview it reports
+// as undefined → the server default, since it is a PR-review surface not a verb.)
+const RUN_MODES = new Set([
+  "remediate",
+  "assess",
+  "review",
+  "refactor",
+  "remediate-refactor",
+  "policygate",
+  "updatedependencies",
+  "modernizedeprecated",
+  "costoptimization",
+  "driftdetect",
+  "complianceaudit",
+]);
+
+// engine mode names that don't lower-case 1:1 onto the Cloud enum. The combined
+// verb "RemediateAndRefactor" reports as "remediate-refactor" (its refactor proof
+// still rides in run.refactor below, driven by toolState — independent of mode).
+const RUN_MODE_ALIASES: Readonly<Record<string, string>> = {
+  remediateandrefactor: "remediate-refactor",
+};
+
+/** Posture from the open concern set — any critical/high ⇒ action-required. */
+export function derivePosture(concerns: Concern[]): CloudPosture {
+  const open = concerns.filter((c) => !c.suppression);
+  if (open.length === 0) return "clean";
+  return open.some((c) => c.severity === "critical" || c.severity === "high")
+    ? "action-required"
+    : "advisory";
+}
+
+/** Map the engine mode name to the Cloud run_mode enum; undefined for an
+ *  unknown/custom mode so the server applies its own default. */
+function normalizeMode(mode: string | undefined): string | undefined {
+  if (!mode) return undefined;
+  const m = mode.toLowerCase();
+  const aliased = RUN_MODE_ALIASES[m] ?? m;
+  return RUN_MODES.has(aliased) ? aliased : undefined;
+}
+
+/** the Cloud-bound refactor (modularise) verdict, mirrors infraweaver-ui
+ *  reportSchema.run.refactor.equivalence_verdict. */
+export type RefactorVerdict =
+  | "equivalence-proven"
+  | "equivalence-failed"
+  | "proposed-unproven";
+
+/**
+ * The refactor (modularise) proof for the Cloud report, or undefined on a
+ * non-refactor run (so the wire omits it). Built from the recorded keys-free
+ * EQUIVALENCE proof when one ran (b.1/b.2/b.3), else the b.4 `proposed — unproven`
+ * marker — an equivalence proof always wins, so a change is never both. Asserts
+ * only what the engine proved: a failed/absent proof is reported as such, never
+ * upgraded. Pure over `toolState`. Mirrors infraweaver-ui reportSchema.run.refactor.
+ */
+export function buildRefactorReport(toolState: ToolState):
+  | {
+      equivalence_verdict: RefactorVerdict;
+      proposed_unproven: boolean;
+      moved_block_count: number;
+      uncovered_moves: number;
+    }
+  | undefined {
+  const session = scanSessionOf(toolState);
+  const eq = session.refactorEquivalence;
+  const proposedUnproven = session.refactorProposedUnproven === true;
+  if (!eq && !proposedUnproven) return undefined;
+  const verdict: RefactorVerdict = eq
+    ? eq.equivalent
+      ? "equivalence-proven"
+      : "equivalence-failed"
+    : "proposed-unproven";
+  return {
+    equivalence_verdict: verdict,
+    proposed_unproven: verdict === "proposed-unproven",
+    moved_block_count: eq?.moves_detected ?? 0,
+    uncovered_moves: eq?.uncovered_moves.length ?? 0,
+  };
+}
+
+/** A `remediation_hint` that is just a URL (checkov's `guideline`, tflint's rule
+ *  link) is the rule's docs page, not guidance — and it already surfaces as `doc_url`
+ *  (ruleDocUrl reads the URL-valued hint). Emitting it as the hint too makes the
+ *  dashboard render a bare URL where actionable text belongs, so drop it here. A real
+ *  text hint (trivy's `Resolution`, the fmt hint) is kept. */
+function textualHint(hint: string | null | undefined): string | undefined {
+  const trimmed = hint?.trim();
+  if (!trimmed || /^https?:\/\//i.test(trimmed)) return undefined;
+  return trimmed;
+}
+
+/** Build the `/report` request body from the finished run's tool state. Exported
+ *  for tests; pure (reads only `toolState` + GitHub env). */
+export function buildReportBody(toolState: ToolState) {
+  const concerns = scanSessionOf(toolState).lastScanConcerns ?? [];
+  const findings = concerns.slice(0, 2000).map((c) => ({
+    concern_id: c.id,
+    concern_key: concernKeyOf(c),
+    source: c.source,
+    rule_id: c.rule_id,
+    severity: c.severity,
+    category: c.category,
+    evidence: c.evidence,
+    file: c.location.file,
+    line: c.location.line ?? undefined,
+    remediation_hint: textualHint(c.remediation_hint),
+    // The offending source line(s) the scanner flagged + the rule's canonical
+    // docs page — so the finding detail shows the exact code and a working
+    // "Open rule docs" link instead of placeholders.
+    code_snippet: c.code_snippet ?? undefined,
+    doc_url: ruleDocUrl(c) ?? undefined,
+    // The maintained-pack control ids this concern evidences (CE / ISO 27001 /
+    // NCSC), the engine⇄Cloud join key the dashboard's per-control verdicts and
+    // required-control gate key on (empty array = no mapping). See
+    // crosswalk.packControlsForConcern — hand-synced with infraweaver-ui pack.ts.
+    compliance: packControlsForConcern(c),
+    // 2b-viii: the composite risk score (CVSS anchor + exposure + fix-with-proof
+    // boost) so the Cloud dashboard can surface the "top N that matter".
+    risk_score: riskScore(c),
+    ...(c.suppression
+      ? {
+          suppressed: true as const,
+          suppression_reason: c.suppression.reason,
+          suppression_source: c.suppression.source,
+          suppression_expires: c.suppression.expires ?? undefined,
+        }
+      : {}),
+  }));
+
+  const runNumber = Number(process.env.GITHUB_RUN_NUMBER);
+  // The refactor (modularise) proof, present only on a Refactor run — keeps the
+  // wire clean (and the server's run.refactor optional) on every other mode.
+  const refactor = buildRefactorReport(toolState);
+  // §5.12 the proven-fix patterns captured this run (a finding-type that went
+  // ✗→✓). Only present when fix_memory is on (capture is gated in verify), and
+  // deduped to one per finding-type. Cloud upserts these into the org library.
+  const provenFixes = dedupeCaptures(
+    scanSessionOf(toolState).provenFixCaptures ?? [],
+  ).map((p) => ({
+    finding_type: p.finding_type,
+    source: p.source ?? undefined,
+    canonical_class: p.canonical_class ?? undefined,
+    category: p.category,
+    title: p.title,
+    description: p.description ?? undefined,
+    remediation_hint: p.remediation_hint ?? undefined,
+    before_example: p.before_example ?? undefined,
+  }));
+  // TC-2.2 the provider-upgrade transforms this run's PLAN proved out. Computed
+  // from the same statement the signed evidence carries, so the org library and
+  // the signed artefact can never disagree about what was proven. Empty unless a
+  // pack applied AND the plan came back clean — a transform that needed a human
+  // is deliberately excluded, since a human intervening is not evidence that the
+  // transform is safe unattended, which is the only claim the counter makes.
+  const session = scanSessionOf(toolState);
+  const provenTransforms = captureProvenTransforms(
+    upgradeStatementOf(session),
+    session.transformMatches ?? [],
+  );
+  return {
+    commit_sha: process.env.GITHUB_SHA || undefined,
+    posture: derivePosture(concerns),
+    // Cyber Essentials posture (0–100) — what the dashboard's "CE SCORE" shows.
+    ce_score: cyberEssentialsScore(concerns),
+    prs_open: toolState.remediationPrsOpened,
+    findings,
+    ...(provenFixes.length ? { proven_fixes: provenFixes } : {}),
+    ...(provenTransforms.length ? { proven_transforms: provenTransforms } : {}),
+    run: {
+      run_number: Number.isInteger(runNumber) ? runNumber : undefined,
+      // The CI run's native id — the same value patchWorkflowRunFields PATCHes
+      // /workflow-run/{id} with, so Cloud can attach the late usage/cost telemetry
+      // to the run row this report creates.
+      external_run_id: process.env.GITHUB_RUN_ID || undefined,
+      mode: normalizeMode(toolState.selectedMode),
+      trigger: process.env.GITHUB_EVENT_NAME || undefined,
+      status: "success" as const,
+      // The engine crosswalk revision each finding's `compliance[]` was computed
+      // against — stamped so a historical run's verdicts stay reproducible after
+      // the rule-pack moves (Cloud stamps its own pack version at ingest).
+      engine_crosswalk_version: CROSSWALK_VERSION,
+      ...(refactor ? { refactor } : {}),
+    },
+  };
+}
+
+/**
+ * Best-effort report of this run to Infraweaver Cloud. No-ops (silently) when:
+ *   - `API_URL` unset — standalone BYOK; don't POST into the marketing host.
+ *   - no scan ran (`lastScanConcerns` undefined) — nothing to report.
+ *   - no credential — neither an `api_token` nor a mintable GitHub Actions OIDC
+ *     token (no `id-token: write`); the run stays pure OSS.
+ * A network/Cloud failure is logged at debug and swallowed — reporting must
+ * never flip an already-successful run outcome.
+ */
+export async function reportToCloud(input: {
+  toolState: ToolState;
+  repo: { owner: string; name: string };
+  apiToken: string | undefined;
+}): Promise<void> {
+  if (!isBackendConfigured()) return;
+  if (!scanSessionOf(input.toolState).lastScanConcerns) {
+    log.debug("cloud report skipped: no scan concerns recorded this run");
+    return;
+  }
+
+  // Prefer the explicit org token; otherwise fall back to a tokenless OIDC token.
+  const credential = await resolveCloudCredential(input.apiToken);
+  if (!credential) {
+    log.debug(
+      "cloud report skipped: no credential (api_token absent + OIDC unavailable)",
+    );
+    return;
+  }
+
+  try {
+    // Inside the try: a throw here (e.g. malformed concern) must surface as a
+    // visible warning, not unwind into finalizeSuccessRun's catch and vanish.
+    const body = buildReportBody(input.toolState);
+    const response = await cloudRequest({
+      path: `/api/repo/${input.repo.owner}/${input.repo.name}/report`,
+      method: "POST",
+      credential,
+      json: body,
+    });
+    if (!response.ok) {
+      // Promoted debug → warning with the response body: a dropped report is the
+      // dashboard silently going stale, which is worth a CI line to diagnose.
+      const detail = await response.text().catch(() => "(no body)");
+      log.warning(`cloud report rejected (${response.status}): ${detail}`);
+      return;
+    }
+    log.info(
+      `» reported ${body.findings.length} finding(s) to ${PRODUCT_NAME} Cloud`,
+    );
+  } catch (error) {
+    log.warning(
+      `cloud report failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}