infraweaver 0.1.0

package/src/utils/humanEditCapture.ts

@@ -0,0 +1,198 @@
+/**
+ * Human-edit capture — the data flywheel.
+ *
+ * When a human edits or rejects a Infraweaver remediation PR, the delta between
+ * what Infraweaver originally committed and what was actually merged is the single
+ * most valuable training/eval signal we can collect: it tells us exactly where a
+ * fix was wrong, over-reaching, or stylistically off. This module computes that
+ * delta as a structured record AND persists it (when a backend is configured).
+ *
+ * SCOPE / SEAM: the pure record-building (`computeHumanEditDelta`,
+ * `deriveRemediationOutcome`) lives here and is unit-tested. PERSISTENCE
+ * (`persistHumanEditRecord`) mirrors the `learnings` seam: it POSTs the record
+ * to the open-core backend ONLY when `API_URL` is set — a standalone BYOK run
+ * has nowhere to persist, so it no-ops cleanly instead of POSTing into the
+ * marketing host. The remaining external dependency is the `pull_request`
+ * `closed`/`merged` EVENT that triggers a capture run; that event wiring is the
+ * hosted product's (it dispatches the action on PR-close). `captureRemediationOutcome`
+ * is the single entry point an event handler calls: build → persist.
+ */
+import { cloudRequest } from "#app/utils/cloudClient";
+import { isBackendConfigured } from "#app/utils/apiUrl";
+import { log } from "#app/utils/cli";
+
+export interface RemediationOutcome {
+  /** the concern id(s) the original Infraweaver PR targeted. */
+  concernIds: string[];
+  /** Infraweaver's original committed patch (unified diff of its commit). */
+  originalFixDiff: string;
+  /** the patch that was actually merged (HEAD of the PR at merge), unified diff. */
+  mergedDiff: string;
+  /** how the PR ended. */
+  outcome: "merged_clean" | "merged_with_edits" | "rejected";
+}
+
+export interface HumanEditRecord {
+  concernIds: string[];
+  outcome: RemediationOutcome["outcome"];
+  /** true when the human changed Infraweaver's fix before merging (or rejected). */
+  humanIntervened: boolean;
+  /** the lines the human ADDED on top of / instead of Infraweaver's fix. */
+  humanAddedLines: string[];
+  /** the lines from Infraweaver's original fix the human REMOVED/replaced. */
+  removedFromOriginal: string[];
+}
+
+/** added (`+`, not `+++`) content lines of a unified diff, sans the leading `+`. */
+function addedLines(diff: string): string[] {
+  return diff
+    .split("\n")
+    .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+    .map((l) => l.slice(1));
+}
+
+/**
+ * Build the structured human-edit record from a finished remediation PR. Pure:
+ * the caller supplies Infraweaver's original diff and the merged diff; this diffs
+ * the two added-line sets to isolate what the human changed. `rejected` (PR
+ * closed unmerged) is always an intervention; `merged_clean` never is; for a
+ * merge, intervention is inferred from whether the merged added-lines differ
+ * from Infraweaver's.
+ */
+export function computeHumanEditDelta(o: RemediationOutcome): HumanEditRecord {
+  const original = addedLines(o.originalFixDiff);
+  const merged = addedLines(o.mergedDiff);
+  const originalSet = new Set(original);
+  const mergedSet = new Set(merged);
+
+  const humanAddedLines = merged.filter((l) => !originalSet.has(l));
+  const removedFromOriginal = original.filter((l) => !mergedSet.has(l));
+
+  const humanIntervened =
+    o.outcome === "rejected" ||
+    (o.outcome === "merged_with_edits" &&
+      (humanAddedLines.length > 0 || removedFromOriginal.length > 0));
+
+  return {
+    concernIds: o.concernIds,
+    outcome: o.outcome,
+    humanIntervened,
+    humanAddedLines,
+    removedFromOriginal,
+  };
+}
+
+/**
+ * Derive the PR outcome from the raw close event: an unmerged close is
+ * `rejected`; a merge whose final added-lines differ from Infraweaver's original
+ * is `merged_with_edits`; an identical merge is `merged_clean`. Pure — the same
+ * added-line comparison `computeHumanEditDelta` uses, lifted so a caller can
+ * classify the event before (or without) building the full delta.
+ */
+export function deriveRemediationOutcome(
+  merged: boolean,
+  originalFixDiff: string,
+  mergedDiff: string,
+): RemediationOutcome["outcome"] {
+  if (!merged) return "rejected";
+  const original = addedLines(originalFixDiff);
+  const mergedSet = new Set(addedLines(mergedDiff));
+  const originalSet = new Set(original);
+  const addedByHuman = addedLines(mergedDiff).some((l) => !originalSet.has(l));
+  const removedInfraweaver = original.some((l) => !mergedSet.has(l));
+  return addedByHuman || removedInfraweaver
+    ? "merged_with_edits"
+    : "merged_clean";
+}
+
+/** the input an event handler hands to `captureRemediationOutcome`: the closed
+ * remediation PR plus the two diffs needed to compute the human-edit delta. */
+export interface RemediationPrClose {
+  prNumber: number;
+  /** whether the PR was merged (vs closed unmerged → rejected). */
+  merged: boolean;
+  /** the concern id(s) the original Infraweaver PR targeted. */
+  concernIds: string[];
+  /** Infraweaver's original committed patch (unified diff of its first commit). */
+  originalFixDiff: string;
+  /** the patch that was actually merged (HEAD of the PR at merge). */
+  mergedDiff: string;
+}
+
+/**
+ * Persist a built human-edit record to the open-core backend. Best-effort and
+ * dormant by default: with no `API_URL` (standalone BYOK) there's nowhere to
+ * persist, so it no-ops and reports `{ persisted: false, reason }` rather than
+ * POSTing into the marketing host. Mirrors `persistLearnings`. Any network
+ * failure is logged, never thrown — capture must never fail a run.
+ */
+export async function persistHumanEditRecord(params: {
+  repo: { owner: string; name: string };
+  apiToken: string;
+  prNumber: number;
+  record: HumanEditRecord;
+}): Promise<{ persisted: boolean; reason?: string }> {
+  if (!isBackendConfigured()) {
+    log.debug(
+      "no backend configured (API_URL unset) — skipping human-edit capture persist",
+    );
+    return { persisted: false, reason: "no_backend" };
+  }
+  try {
+    const response = await cloudRequest({
+      path: `/api/repo/${params.repo.owner}/${params.repo.name}/remediation-outcomes`,
+      method: "POST",
+      credential: params.apiToken,
+      json: { pr_number: params.prNumber, ...params.record },
+      timeoutMs: 10_000,
+    });
+    if (!response.ok) {
+      const error = await response.text().catch(() => "(no body)");
+      log.warning(
+        `human-edit capture persist failed (${response.status}): ${error}`,
+      );
+      return { persisted: false, reason: `http_${response.status}` };
+    }
+    log.info(
+      `» human-edit record captured for PR #${params.prNumber} (${params.record.outcome})`,
+    );
+    return { persisted: true };
+  } catch (err) {
+    log.warning(
+      `human-edit capture persist failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { persisted: false, reason: "error" };
+  }
+}
+
+/**
+ * The single entry point for human-edit capture: classify the close event, build the
+ * structured delta, and persist it (no-op without a backend). Returns the record
+ * and whether it was persisted, so the caller can log/surface it. Pure parts are
+ * separately testable (`deriveRemediationOutcome` / `computeHumanEditDelta`);
+ * this just composes them with the dormant persistence seam.
+ */
+export async function captureRemediationOutcome(params: {
+  repo: { owner: string; name: string };
+  apiToken: string;
+  event: RemediationPrClose;
+}): Promise<{ record: HumanEditRecord; persisted: boolean; reason?: string }> {
+  const outcome = deriveRemediationOutcome(
+    params.event.merged,
+    params.event.originalFixDiff,
+    params.event.mergedDiff,
+  );
+  const record = computeHumanEditDelta({
+    concernIds: params.event.concernIds,
+    originalFixDiff: params.event.originalFixDiff,
+    mergedDiff: params.event.mergedDiff,
+    outcome,
+  });
+  const result = await persistHumanEditRecord({
+    repo: params.repo,
+    apiToken: params.apiToken,
+    prNumber: params.event.prNumber,
+    record,
+  });
+  return { record, ...result };
+}

package/src/utils/infraweaverConfig.ts

@@ -0,0 +1,202 @@
+/**
+ * Repo-committed `.infraweaver.yml` / `.infraweaver.json` config (the follow-up
+ * to the unified `tools_enabled` input). A thin layer that sits **under** the
+ * action inputs: an
+ * explicit workflow input always wins; the file only fills the gaps. It versions
+ * the toolchain + scoping policy *with the code* (and doubles as the auditable
+ * record of which non-permissive tools the repo owner opted into), so the
+ * workflow file can stay minimal and the policy lives next to the Terraform.
+ *
+ * Scope is deliberate — only repo-level **policy** knobs live here. Each maps
+ * 1:1 to the matching action input and flows through the SAME parser, so the file
+ * and the input validate identically. Secrets (`module_fetch_token`) and
+ * per-run/workflow knobs (`mode`, `max_prs`, `base_branch`, `allow_replace`) are
+ * intentionally NOT read from the file: a committed file is the wrong place for a
+ * credential, and the run's shape belongs to the workflow that dispatches it.
+ *
+ * Trust boundary: `.infraweaver.yml` is controlled by whoever can push to the repo
+ * — the same surface as the Terraform being remediated. It can only RELAX within
+ * the licence gate's structure (naming a non-permissive tool is the repo owner's
+ * licence acknowledgement, exactly as on the input) and it can never disable the
+ * required substrate. A workflow author who needs to *enforce* a policy sets the
+ * action input, which wins over the file.
+ *
+ * Degrade-green: a missing file is silent; malformed YAML, a non-mapping
+ * document, an unknown key, or a value of the wrong shape yields a warning and is
+ * ignored — never a hard failure.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { CONFIG_FILE, CONFIG_FILE_JSON, CONFIG_FILE_YAML } from "#app/brand";
+import { log } from "#app/utils/cli";
+import { normalizeExtends, resolvePresets } from "#app/utils/presets";
+
+/** filenames checked, in order; the first that exists wins. `.infraweaver.json` is
+ * listed first so the JSON form takes precedence if a repo (mis)commits both. */
+export const INFRAWEAVER_CONFIG_FILENAMES = [
+  CONFIG_FILE_JSON,
+  CONFIG_FILE,
+  CONFIG_FILE_YAML,
+] as const;
+
+/** the repo-level keys `.infraweaver.yml` may set. Each is the snake_case name of
+ * the matching action input, so the file value can be fed straight through the
+ * input's own parser in `resolvePayload`. */
+export const INFRAWEAVER_CONFIG_KEYS = [
+  "tools_enabled",
+  "protected_paths",
+  "allowed_paths",
+  "scan_scope",
+  "iac_languages",
+  "language",
+  "severity_threshold",
+  "grouping",
+  "autonomy_threshold",
+  "module_catalogue",
+  "required_controls",
+] as const;
+
+export type InfraweaverConfigKey = (typeof INFRAWEAVER_CONFIG_KEYS)[number];
+
+/** normalized string values (lists newline-joined), keyed by input name. */
+export type InfraweaverFileValues = Partial<
+  Record<InfraweaverConfigKey, string>
+>;
+
+export interface ParsedInfraweaverConfig {
+  values: InfraweaverFileValues;
+  /** non-fatal problems (malformed value, unknown key) for the caller to log. */
+  warnings: string[];
+}
+
+const KEY_SET: ReadonlySet<string> = new Set(INFRAWEAVER_CONFIG_KEYS);
+// Keys parsed by a dedicated path, not the scalar value pipeline: `suppressions`
+// (the suppression-policy block) and `extends` (shareable presets).
+const STRUCTURED_KEYS: ReadonlySet<string> = new Set([
+  "suppressions",
+  "extends",
+]);
+
+/**
+ * Normalize a YAML value to the string shape the action-input parsers expect:
+ * a scalar → its trimmed string; a list → newline-joined (the tool-selection,
+ * glob, and module-catalogue parsers all split on newlines *or* commas). Returns
+ * null for an unusable value (a mapping, an empty/blank string, null) so the
+ * caller can warn and skip it.
+ */
+function normalizeValue(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value.trim() || null;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (Array.isArray(value)) {
+    const items = value
+      .filter((v) => v !== null && v !== undefined && typeof v !== "object")
+      .map((v) => String(v).trim())
+      .filter(Boolean);
+    return items.length > 0 ? items.join("\n") : null;
+  }
+  return null; // a nested mapping isn't a valid value for any of these keys.
+}
+
+/**
+ * Parse raw `.infraweaver.yml`/`.infraweaver.json` text into normalized string values
+ * + warnings. Pure — no I/O, no logging — so the parsing/validation is
+ * unit-testable. `format` selects the syntax (and shapes the warning wording);
+ * everything after the document is parsed is identical, since JSON and YAML both
+ * yield a plain object here.
+ */
+export function parseInfraweaverConfig(
+  raw: string,
+  format: "yaml" | "json" = "yaml",
+): ParsedInfraweaverConfig {
+  const label = format === "json" ? CONFIG_FILE_JSON : CONFIG_FILE;
+  let doc: unknown;
+  if (format === "json") {
+    // An empty/whitespace-only file is a valid no-op; JSON.parse would throw on it.
+    if (raw.trim() === "") return { values: {}, warnings: [] };
+    try {
+      doc = JSON.parse(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      return {
+        values: {},
+        warnings: [`${label} is not valid JSON — ignored (${detail})`],
+      };
+    }
+  } else {
+    try {
+      doc = parseYaml(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      return {
+        values: {},
+        warnings: [`${label} is not valid YAML — ignored (${detail})`],
+      };
+    }
+  }
+  // an empty file / only comments parses to null|undefined — a valid no-op.
+  if (doc === null || doc === undefined) return { values: {}, warnings: [] };
+  if (typeof doc !== "object" || Array.isArray(doc)) {
+    const shape =
+      format === "json" ? "JSON object" : "YAML mapping (key: value)";
+    return { values: {}, warnings: [`${label} must be a ${shape} — ignored`] };
+  }
+
+  const record = doc as Record<string, unknown>;
+  const warnings: string[] = [];
+
+  // Resolve `extends` presets FIRST so the file's own keys (handled below) can
+  // override them. Precedence: file key > later preset > earlier preset.
+  const presets = resolvePresets(normalizeExtends(record.extends));
+  warnings.push(...presets.warnings);
+  const values: InfraweaverFileValues = { ...presets.values };
+
+  for (const [key, value] of Object.entries(record)) {
+    if (STRUCTURED_KEYS.has(key)) continue;
+    if (!KEY_SET.has(key)) {
+      warnings.push(`${label}: ignoring unrecognised key "${key}"`);
+      continue;
+    }
+    const normalized = normalizeValue(value);
+    if (normalized === null) {
+      warnings.push(
+        `${label}: ignoring "${key}" — expected a string or a list of strings`,
+      );
+      continue;
+    }
+    values[key as InfraweaverConfigKey] = normalized;
+  }
+  return { values, warnings };
+}
+
+/**
+ * Read + parse the repo's `.infraweaver.yml` (first of the supported filenames
+ * found under `cwd`). Returns the normalized values, logging any warnings. A
+ * missing file resolves to `{}` silently — the common, valid case.
+ */
+export function loadInfraweaverConfig(
+  cwd: string | undefined,
+): InfraweaverFileValues {
+  const root = cwd ?? process.cwd();
+  for (const name of INFRAWEAVER_CONFIG_FILENAMES) {
+    let raw: string;
+    try {
+      raw = readFileSync(join(root, name), "utf-8");
+    } catch {
+      continue; // not this filename — try the next, or fall through to {}.
+    }
+    const { values, warnings } = parseInfraweaverConfig(
+      raw,
+      name.endsWith(".json") ? "json" : "yaml",
+    );
+    for (const w of warnings) log.warning(`» ${w}`);
+    if (Object.keys(values).length > 0) {
+      log.info(`» loaded ${name} (${Object.keys(values).join(", ")})`);
+    }
+    return values;
+  }
+  return {};
+}

package/src/utils/install.ts

@@ -0,0 +1,279 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  createWriteStream,
+  existsSync,
+  readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import semver from "semver";
+import { log } from "#app/utils/cli";
+import { getTempDir } from "#app/utils/env";
+
+// generous ceiling sized for the biggest artifact (a full CLI tarball on a
+// slow runner) — a stalled CDN must fail the install instead of hanging the
+// whole action with no timeout at all.
+const INSTALL_FETCH_TIMEOUT_MS = 120_000;
+
+export interface InstallFromNpmTarballParams {
+  packageName: string;
+  version: string;
+  executablePath: string;
+  installDependencies?: boolean;
+}
+
+/**
+ * The `dist` block npm returns for a published version. `integrity` is a
+ * Subresource-Integrity string (`sha512-<base64>`); `shasum` is the legacy hex
+ * SHA-1. Every public-registry version carries at least one.
+ */
+export interface NpmDist {
+  integrity?: string;
+  shasum?: string;
+}
+
+interface NpmVersionManifest {
+  dist?: NpmDist;
+}
+
+interface NpmRegistryData {
+  "dist-tags": { latest: string };
+  versions: Record<string, NpmVersionManifest | undefined>;
+}
+
+/** npm path-encodes a scoped name's slash (`@scope/name` → `@scope%2Fname`). */
+function encodePackageName(packageName: string): string {
+  return packageName.startsWith("@")
+    ? `@${packageName.slice(1).split("/").join("%2F")}`
+    : packageName;
+}
+
+/**
+ * Verify a downloaded tarball against the digest the registry published for
+ * that exact version, and throw if it doesn't match.
+ *
+ * This is what makes a consumer's `uses: infraweaver@<sha>` pin mean something:
+ * the action itself is pinned by SHA, but it then fetches an agent CLI at
+ * runtime. Without this check a compromised registry/CDN — or anything able to
+ * intercept the download — could serve arbitrary code into a run that reads the
+ * customer's repository. The version is already pinned by `package.json` (see
+ * `getDevDependencyVersion`, which refuses a range); this pins the *bytes*.
+ *
+ * Fails **closed**: no digest published ⇒ we refuse to install, rather than
+ * silently degrading to unverified. A registry that serves no digest is exactly
+ * the case worth stopping on.
+ */
+export function verifyTarballIntegrity(
+  tarballPath: string,
+  dist: NpmDist | undefined,
+  descriptor: string,
+): void {
+  const integrity = dist?.integrity;
+  const shasum = dist?.shasum;
+
+  if (!integrity && !shasum) {
+    throw new Error(
+      `Refusing to install ${descriptor}: the registry published no integrity digest ` +
+        `(neither dist.integrity nor dist.shasum), so the download cannot be verified.`,
+    );
+  }
+
+  const bytes = readFileSync(tarballPath);
+
+  // prefer SRI (sha512/sha384/sha256) over the legacy SHA-1 shasum
+  if (integrity) {
+    // an SRI string may carry several space-separated digests; any one matching
+    // is a pass, which is how SRI is specified.
+    const candidates = integrity.trim().split(/\s+/).filter(Boolean);
+    for (const candidate of candidates) {
+      const separator = candidate.indexOf("-");
+      if (separator === -1) continue;
+      const algorithm = candidate.slice(0, separator);
+      const expected = candidate.slice(separator + 1);
+      let actual: string;
+      try {
+        actual = createHash(algorithm).update(bytes).digest("base64");
+      } catch {
+        continue; // unknown algorithm — try the next candidate
+      }
+      if (actual === expected) return;
+    }
+    throw new Error(
+      `Integrity check FAILED for ${descriptor}: the downloaded tarball does not match ` +
+        `the registry's published digest (${integrity}). Refusing to execute it.`,
+    );
+  }
+
+  const actualShasum = createHash("sha1").update(bytes).digest("hex");
+  if (actualShasum !== shasum) {
+    throw new Error(
+      `Integrity check FAILED for ${descriptor}: the downloaded tarball does not match ` +
+        `the registry's published shasum (expected ${shasum}, got ${actualShasum}). ` +
+        `Refusing to execute it.`,
+    );
+  }
+}
+
+/**
+ * Install a CLI tool from an npm package tarball
+ * Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export async function installFromNpmTarball(
+  params: InstallFromNpmTarballParams,
+): Promise<string> {
+  const tempDir = getTempDir();
+
+  const extractedDir = join(tempDir, "package");
+  const cliPath = join(extractedDir, params.executablePath);
+
+  if (existsSync(cliPath)) {
+    log.debug(`» using cached binary at ${cliPath}`);
+    return cliPath;
+  }
+
+  const npmRegistry = process.env.NPM_REGISTRY || "https://registry.npmjs.org";
+  const encodedName = encodePackageName(params.packageName);
+
+  // Resolve version if it's a range or "latest", capturing the published digest
+  // from the same document so the common path costs one request, not two.
+  let resolvedVersion = params.version;
+  let dist: NpmDist | undefined;
+  if (
+    params.version.startsWith("^") ||
+    params.version.startsWith("~") ||
+    params.version === "latest"
+  ) {
+    log.debug(`» resolving version for ${params.version}...`);
+    try {
+      const registryResponse = await fetch(`${npmRegistry}/${encodedName}`, {
+        signal: AbortSignal.timeout(INSTALL_FETCH_TIMEOUT_MS),
+      });
+      if (!registryResponse.ok) {
+        throw new Error(`Failed to query registry: ${registryResponse.status}`);
+      }
+      const registryData = (await registryResponse.json()) as NpmRegistryData;
+      if (params.version === "latest") {
+        resolvedVersion = registryData["dist-tags"].latest;
+      } else {
+        // honour the range. previously this took `dist-tags.latest` for ANY
+        // range, so `^1.2.3` could install 3.x — a silent major bump.
+        const available = Object.keys(registryData.versions ?? {});
+        const best = semver.maxSatisfying(available, params.version);
+        if (!best) {
+          throw new Error(
+            `No published version of ${params.packageName} satisfies "${params.version}"`,
+          );
+        }
+        resolvedVersion = best;
+      }
+      dist = registryData.versions?.[resolvedVersion]?.dist;
+      log.debug(`» resolved to version ${resolvedVersion}`);
+    } catch (error) {
+      log.warning(
+        `Failed to resolve version from registry: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      throw error;
+    }
+  }
+
+  // Exact pin: fetch just that version's manifest for its digest.
+  if (!dist) {
+    const manifestUrl = `${npmRegistry}/${encodedName}/${resolvedVersion}`;
+    log.debug(`» fetching integrity metadata from ${manifestUrl}...`);
+    const manifestResponse = await fetch(manifestUrl, {
+      signal: AbortSignal.timeout(INSTALL_FETCH_TIMEOUT_MS),
+    });
+    if (!manifestResponse.ok) {
+      throw new Error(
+        `Failed to fetch integrity metadata for ${params.packageName}@${resolvedVersion}: ${manifestResponse.status}`,
+      );
+    }
+    dist = ((await manifestResponse.json()) as NpmVersionManifest).dist;
+  }
+
+  log.debug(`» installing ${params.packageName}@${resolvedVersion}...`);
+
+  const tarballPath = join(tempDir, "package.tgz");
+
+  // Download tarball from npm. Scoped names keep the encoded form in the path
+  // but use the bare name in the filename (@scope/name -> name-1.2.3.tgz).
+  const tarballFileName = params.packageName.startsWith("@")
+    ? params.packageName.split("/")[1]
+    : params.packageName;
+  const tarballUrl = `${npmRegistry}/${encodedName}/-/${tarballFileName}-${resolvedVersion}.tgz`;
+
+  log.debug(`» downloading from ${tarballUrl}...`);
+  const response = await fetch(tarballUrl, {
+    signal: AbortSignal.timeout(INSTALL_FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download tarball: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  // Write tarball to file
+  if (!response.body) throw new Error("Response body is null");
+  const fileStream = createWriteStream(tarballPath);
+  await pipeline(response.body, fileStream);
+  log.debug(`» downloaded tarball to ${tarballPath}`);
+
+  // Verify BEFORE extracting — an unverified tarball is never unpacked, let
+  // alone executed. Throws (fail-closed) on mismatch or missing digest.
+  verifyTarballIntegrity(
+    tarballPath,
+    dist,
+    `${params.packageName}@${resolvedVersion}`,
+  );
+  log.debug(
+    `» integrity verified for ${params.packageName}@${resolvedVersion}`,
+  );
+
+  // Extract tarball
+  log.debug(`» extracting tarball...`);
+  const extractResult = spawnSync("tar", ["-xzf", tarballPath, "-C", tempDir], {
+    stdio: "pipe",
+    encoding: "utf-8",
+  });
+  if (extractResult.status !== 0) {
+    throw new Error(
+      `Failed to extract tarball: ${extractResult.stderr || extractResult.stdout || "Unknown error"}`,
+    );
+  }
+
+  if (!existsSync(cliPath)) {
+    throw new Error(`Executable not found in extracted package at ${cliPath}`);
+  }
+
+  // Install dependencies if requested
+  if (params.installDependencies) {
+    log.debug(`» installing dependencies for ${params.packageName}...`);
+    const installResult = spawnSync("npm", ["install", "--production"], {
+      cwd: extractedDir,
+      stdio: "pipe",
+      encoding: "utf-8",
+      // @anthropic-ai/claude-code (2.1.113+) guards its `prepare` script with an
+      // `AUTHORIZED` env check that hard-fails any non-release install. we need
+      // its `postinstall` (which copies the native binary from the platform
+      // optionalDependency over the bin/claude.exe stub) to run, so we set the
+      // flag to no-op the guard. harmless for packages without such a guard.
+      env: { ...process.env, AUTHORIZED: "1" },
+    });
+    if (installResult.status !== 0) {
+      throw new Error(
+        `Failed to install dependencies: ${installResult.stderr || installResult.stdout || "Unknown error"}`,
+      );
+    }
+    log.debug(`» dependencies installed`);
+  }
+
+  // Make the file executable
+  chmodSync(cliPath, 0o755);
+
+  log.debug(`» ${params.packageName} installed at ${cliPath}`);
+
+  return cliPath;
+}