getculpa 1.0.9 → 1.1.0

package/lib/fetch.d.mts

@@ -1,17 +1,17 @@
-export declare const ORIGIN: string;
-export function targetTriple(platform?: string, arch?: string): string;
-
-export interface FetchOptions {
-  vendorDir?: string;
-  origin?: string;
-  trustedHosts?: Set<string>;
-  allowInsecureHttp?: boolean;
-}
-
-export interface FetchResult {
-  dest: string;
-  sha256: string;
-}
-
-export function fetchLauncher(opts?: FetchOptions): Promise<FetchResult>;
-export function fetchCollectord(opts?: FetchOptions): Promise<FetchResult>;
+export declare const ORIGIN: string;
+export function targetTriple(platform?: string, arch?: string): string;
+
+export interface FetchOptions {
+  vendorDir?: string;
+  origin?: string;
+  trustedHosts?: Set<string>;
+  allowInsecureHttp?: boolean;
+}
+
+export interface FetchResult {
+  dest: string;
+  sha256: string;
+}
+
+export function fetchLauncher(opts?: FetchOptions): Promise<FetchResult>;
+export function fetchCollectord(opts?: FetchOptions): Promise<FetchResult>;

package/lib/fetch.mjs

@@ -1,211 +1,211 @@
-// CF20-T3 — checksum-verified GitHub-release fetch, extracted from the
-// original scripts/install.js (AU-011) so it can be reused for the
-// collector binary and unit-tested against a local fixture server. Every
-// security property of the original is kept byte-for-byte:
-//   - host allowlist enforced on every redirect hop (github.com,
-//     objects.githubusercontent.com, release-assets.githubusercontent.com)
-//   - https only
-//   - bounded redirects (MAX_REDIRECTS)
-//   - size caps enforced WHILE streaming, not after buffering
-//   - write-temp + rename (never a half-written executable at the dest)
-//   - sha256 verified against the release's published checksums file before
-//     the file is ever written to its final path
-//
-// The one behavioral extension: fetchCollectord() treats "no checksum line
-// published for this asset" as an EXPECTED, non-fatal outcome (the release
-// process may ship without a collectord for a given triple yet) — everything
-// else, including a checksum MISMATCH, still fails closed exactly like the
-// launcher fetch.
-
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.join(__dirname, "..");
-
-// The ONE origin — mirrors native/culpa-launcher/src/origin.rs. Never read
-// from env or config. D-094: repointed to the public releases-only mirror
-// (MyaigiDev/culpa-releases); the source repo (myaigidev/culpa) stays
-// private.
-// Exported so tests can pin the production origin (CF21-T5 review: a revert
-// of this constant would 404 every fresh install and no injected-fixture test
-// can see it).
-export const ORIGIN = "https://github.com/MyaigiDev/culpa-releases/releases/latest/download";
-const TRUSTED_HOSTS = new Set([
-  "github.com",
-  "objects.githubusercontent.com",
-  "release-assets.githubusercontent.com",
-]);
-const MAX_REDIRECTS = 5;
-
-export function targetTriple(platform = process.platform, arch = process.arch) {
-  if (platform === "win32" && arch === "x64") return "x86_64-pc-windows-msvc";
-  if (platform === "linux" && arch === "x64") return "x86_64-unknown-linux-gnu";
-  if (platform === "darwin" && arch === "x64") return "x86_64-apple-darwin";
-  if (platform === "darwin" && arch === "arm64") return "aarch64-apple-darwin";
-  throw new Error(`unsupported platform: ${platform}/${arch}`);
-}
-
-// allowInsecureHttp defaults false and is ONLY ever set by the fixture-server
-// tests (see tests/npm-core-fetch.test.ts) — no production call site (the
-// fetchLauncher()/fetchCollectord() callers in scripts/install.js) passes
-// it, so the real https-only enforcement is unchanged.
-function assertTrustedUrl(u, trustedHosts, allowInsecureHttp) {
-  const protocolOk = u.protocol === "https:" || (allowInsecureHttp && u.protocol === "http:");
-  if (!protocolOk) throw new Error(`${u}: only https is trusted (got ${u.protocol})`);
-  if (!trustedHosts.has(u.hostname)) throw new Error(`${u}: untrusted redirect host refused (${u.hostname})`);
-}
-
-// Follows redirects manually so every hop is pinned to https + a trusted
-// host, up to MAX_REDIRECTS hops. `timeoutMs` bounds each hop individually.
-async function fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp) {
-  let current = new URL(url);
-  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
-    assertTrustedUrl(current, trustedHosts, allowInsecureHttp);
-    const res = await fetch(current, { redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
-    if (res.status >= 300 && res.status < 400) {
-      const location = res.headers.get("location");
-      if (!location) throw new Error(`${current}: redirect with no Location header`);
-      current = new URL(location, current);
-      continue;
-    }
-    if (res.status === 404) {
-      const err = new Error(`GET ${current} -> 404`);
-      err.notFound = true;
-      throw err;
-    }
-    if (!res.ok) throw new Error(`GET ${current} -> ${res.status}`);
-    return res;
-  }
-  throw new Error(`${url}: too many redirects (> ${MAX_REDIRECTS})`);
-}
-
-// Enforces maxBytes WHILE STREAMING so a hostile/misconfigured response with
-// no (or a lying) Content-Length cannot be buffered past the cap before it
-// is checked.
-async function fetchBytes(url, maxBytes, timeoutMs, trustedHosts, allowInsecureHttp) {
-  const res = await fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp);
-  if (!res.body) throw new Error(`${url}: response has no body`);
-  const reader = res.body.getReader();
-  const chunks = [];
-  let total = 0;
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    total += value.length;
-    if (total > maxBytes) {
-      await reader.cancel();
-      throw new Error(`${url}: response exceeds ${maxBytes} bytes`);
-    }
-    chunks.push(value);
-  }
-  return Buffer.concat(chunks);
-}
-
-function sha256Hex(buf) {
-  return crypto.createHash("sha256").update(buf).digest("hex");
-}
-
-// CF20-R: the checksums file is `sha256sum`'s own output — one line per
-// asset, "<sha256>  <filename>" (verified format: release-cli.yml runs
-// `sha256sum culpa-launcher-* culpa-collectord-*` on ubuntu-latest, GNU
-// coreutils' default text-mode two-space separator; tests/npm-core-fetch.test.ts's
-// fixtures construct lines the same way). `endsWith(assetName)` was a
-// substring match on the WHOLE line, not the filename field — a shorter
-// asset name that happens to be a suffix of an unrelated line (or a
-// malformed/commented line ending in the same text) could match the wrong
-// entry. Split on whitespace and compare the filename field exactly.
-function findChecksumLine(checksumsText, assetName) {
-  const line = checksumsText
-    .split("\n")
-    .map((l) => l.trim())
-    .find((l) => l.split(/\s+/)[1] === assetName);
-  if (!line) return null;
-  const expected = line.split(/\s+/)[0];
-  if (!/^[0-9a-f]{64}$/.test(expected)) throw new Error("malformed checksum line");
-  return expected;
-}
-
-function writeVerified(destDir, destName, binary) {
-  fs.mkdirSync(destDir, { recursive: true });
-  const dest = path.join(destDir, destName);
-  const tmp = `${dest}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, binary);
-  fs.renameSync(tmp, dest);
-  if (process.platform !== "win32") fs.chmodSync(dest, 0o755);
-  return dest;
-}
-
-// origin/trustedHosts/allowInsecureHttp are all injectable — this is what
-// makes the fixture-server tests possible without touching the real GitHub
-// origin or weakening production's https-only enforcement.
-async function fetchVerifiedAsset({
-  assetName,
-  destDir,
-  destName,
-  maxBytes,
-  origin = ORIGIN,
-  trustedHosts = TRUSTED_HOSTS,
-  allowInsecureHttp = false,
-}) {
-  const checksumsBuf = await fetchBytes(
-    `${origin}/culpa-launcher-checksums.txt`,
-    64 * 1024,
-    120_000,
-    trustedHosts,
-    allowInsecureHttp,
-  );
-  const expected = findChecksumLine(checksumsBuf.toString("utf8"), assetName);
-  if (!expected) {
-    const err = new Error(`no checksum published for ${assetName}`);
-    err.notFound = true;
-    throw err;
-  }
-  const binary = await fetchBytes(`${origin}/${assetName}`, maxBytes, 15 * 60_000, trustedHosts, allowInsecureHttp);
-  const actual = sha256Hex(binary);
-  if (actual !== expected) {
-    throw new Error(`checksum mismatch for ${assetName}: expected ${expected}, got ${actual}`);
-  }
-  const dest = writeVerified(destDir, destName, binary);
-  return { dest, sha256: actual };
-}
-
-export async function fetchLauncher(opts = {}) {
-  const triple = targetTriple();
-  const exe = process.platform === "win32" ? ".exe" : "";
-  const assetName = `culpa-launcher-${triple}${exe}`;
-  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
-  const result = await fetchVerifiedAsset({
-    assetName,
-    destDir: vendorDir,
-    destName: `culpa-launcher${exe}`,
-    maxBytes: 64 * 1024 * 1024,
-    origin: opts.origin,
-    trustedHosts: opts.trustedHosts,
-    allowInsecureHttp: opts.allowInsecureHttp,
-  });
-  console.log(`getculpa: installed culpa launcher (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
-  return result;
-}
-
-// Graceful-degrade case lives here, not in the caller: "not published for
-// this release yet" is the ONE outcome that must not abort the install.
-export async function fetchCollectord(opts = {}) {
-  const triple = targetTriple();
-  const exe = process.platform === "win32" ? ".exe" : "";
-  const assetName = `culpa-collectord-${triple}${exe}`;
-  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
-  const result = await fetchVerifiedAsset({
-    assetName,
-    destDir: vendorDir,
-    destName: `culpa-collectord${exe}`,
-    maxBytes: 64 * 1024 * 1024,
-    origin: opts.origin,
-    trustedHosts: opts.trustedHosts,
-    allowInsecureHttp: opts.allowInsecureHttp,
-  });
-  console.log(`getculpa: installed capture collector (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
-  return result;
-}
+// CF20-T3 — checksum-verified GitHub-release fetch, extracted from the
+// original scripts/install.js (AU-011) so it can be reused for the
+// collector binary and unit-tested against a local fixture server. Every
+// security property of the original is kept byte-for-byte:
+//   - host allowlist enforced on every redirect hop (github.com,
+//     objects.githubusercontent.com, release-assets.githubusercontent.com)
+//   - https only
+//   - bounded redirects (MAX_REDIRECTS)
+//   - size caps enforced WHILE streaming, not after buffering
+//   - write-temp + rename (never a half-written executable at the dest)
+//   - sha256 verified against the release's published checksums file before
+//     the file is ever written to its final path
+//
+// The one behavioral extension: fetchCollectord() treats "no checksum line
+// published for this asset" as an EXPECTED, non-fatal outcome (the release
+// process may ship without a collectord for a given triple yet) — everything
+// else, including a checksum MISMATCH, still fails closed exactly like the
+// launcher fetch.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+// The ONE origin — mirrors native/culpa-launcher/src/origin.rs. Never read
+// from env or config. D-094: repointed to the public releases-only mirror
+// (MyaigiDev/culpa-releases); the source repo (myaigidev/culpa) stays
+// private.
+// Exported so tests can pin the production origin (CF21-T5 review: a revert
+// of this constant would 404 every fresh install and no injected-fixture test
+// can see it).
+export const ORIGIN = "https://github.com/MyaigiDev/culpa-releases/releases/latest/download";
+const TRUSTED_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+  "release-assets.githubusercontent.com",
+]);
+const MAX_REDIRECTS = 5;
+
+export function targetTriple(platform = process.platform, arch = process.arch) {
+  if (platform === "win32" && arch === "x64") return "x86_64-pc-windows-msvc";
+  if (platform === "linux" && arch === "x64") return "x86_64-unknown-linux-gnu";
+  if (platform === "darwin" && arch === "x64") return "x86_64-apple-darwin";
+  if (platform === "darwin" && arch === "arm64") return "aarch64-apple-darwin";
+  throw new Error(`unsupported platform: ${platform}/${arch}`);
+}
+
+// allowInsecureHttp defaults false and is ONLY ever set by the fixture-server
+// tests (see tests/npm-core-fetch.test.ts) — no production call site (the
+// fetchLauncher()/fetchCollectord() callers in scripts/install.js) passes
+// it, so the real https-only enforcement is unchanged.
+function assertTrustedUrl(u, trustedHosts, allowInsecureHttp) {
+  const protocolOk = u.protocol === "https:" || (allowInsecureHttp && u.protocol === "http:");
+  if (!protocolOk) throw new Error(`${u}: only https is trusted (got ${u.protocol})`);
+  if (!trustedHosts.has(u.hostname)) throw new Error(`${u}: untrusted redirect host refused (${u.hostname})`);
+}
+
+// Follows redirects manually so every hop is pinned to https + a trusted
+// host, up to MAX_REDIRECTS hops. `timeoutMs` bounds each hop individually.
+async function fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp) {
+  let current = new URL(url);
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    assertTrustedUrl(current, trustedHosts, allowInsecureHttp);
+    const res = await fetch(current, { redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (!location) throw new Error(`${current}: redirect with no Location header`);
+      current = new URL(location, current);
+      continue;
+    }
+    if (res.status === 404) {
+      const err = new Error(`GET ${current} -> 404`);
+      err.notFound = true;
+      throw err;
+    }
+    if (!res.ok) throw new Error(`GET ${current} -> ${res.status}`);
+    return res;
+  }
+  throw new Error(`${url}: too many redirects (> ${MAX_REDIRECTS})`);
+}
+
+// Enforces maxBytes WHILE STREAMING so a hostile/misconfigured response with
+// no (or a lying) Content-Length cannot be buffered past the cap before it
+// is checked.
+async function fetchBytes(url, maxBytes, timeoutMs, trustedHosts, allowInsecureHttp) {
+  const res = await fetchTrusted(url, timeoutMs, trustedHosts, allowInsecureHttp);
+  if (!res.body) throw new Error(`${url}: response has no body`);
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`${url}: response exceeds ${maxBytes} bytes`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+// CF20-R: the checksums file is `sha256sum`'s own output — one line per
+// asset, "<sha256>  <filename>" (verified format: release-cli.yml runs
+// `sha256sum culpa-launcher-* culpa-collectord-*` on ubuntu-latest, GNU
+// coreutils' default text-mode two-space separator; tests/npm-core-fetch.test.ts's
+// fixtures construct lines the same way). `endsWith(assetName)` was a
+// substring match on the WHOLE line, not the filename field — a shorter
+// asset name that happens to be a suffix of an unrelated line (or a
+// malformed/commented line ending in the same text) could match the wrong
+// entry. Split on whitespace and compare the filename field exactly.
+function findChecksumLine(checksumsText, assetName) {
+  const line = checksumsText
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.split(/\s+/)[1] === assetName);
+  if (!line) return null;
+  const expected = line.split(/\s+/)[0];
+  if (!/^[0-9a-f]{64}$/.test(expected)) throw new Error("malformed checksum line");
+  return expected;
+}
+
+function writeVerified(destDir, destName, binary) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, destName);
+  const tmp = `${dest}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, binary);
+  fs.renameSync(tmp, dest);
+  if (process.platform !== "win32") fs.chmodSync(dest, 0o755);
+  return dest;
+}
+
+// origin/trustedHosts/allowInsecureHttp are all injectable — this is what
+// makes the fixture-server tests possible without touching the real GitHub
+// origin or weakening production's https-only enforcement.
+async function fetchVerifiedAsset({
+  assetName,
+  destDir,
+  destName,
+  maxBytes,
+  origin = ORIGIN,
+  trustedHosts = TRUSTED_HOSTS,
+  allowInsecureHttp = false,
+}) {
+  const checksumsBuf = await fetchBytes(
+    `${origin}/culpa-launcher-checksums.txt`,
+    64 * 1024,
+    120_000,
+    trustedHosts,
+    allowInsecureHttp,
+  );
+  const expected = findChecksumLine(checksumsBuf.toString("utf8"), assetName);
+  if (!expected) {
+    const err = new Error(`no checksum published for ${assetName}`);
+    err.notFound = true;
+    throw err;
+  }
+  const binary = await fetchBytes(`${origin}/${assetName}`, maxBytes, 15 * 60_000, trustedHosts, allowInsecureHttp);
+  const actual = sha256Hex(binary);
+  if (actual !== expected) {
+    throw new Error(`checksum mismatch for ${assetName}: expected ${expected}, got ${actual}`);
+  }
+  const dest = writeVerified(destDir, destName, binary);
+  return { dest, sha256: actual };
+}
+
+export async function fetchLauncher(opts = {}) {
+  const triple = targetTriple();
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const assetName = `culpa-launcher-${triple}${exe}`;
+  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
+  const result = await fetchVerifiedAsset({
+    assetName,
+    destDir: vendorDir,
+    destName: `culpa-launcher${exe}`,
+    maxBytes: 64 * 1024 * 1024,
+    origin: opts.origin,
+    trustedHosts: opts.trustedHosts,
+    allowInsecureHttp: opts.allowInsecureHttp,
+  });
+  console.log(`getculpa: installed culpa launcher (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
+  return result;
+}
+
+// Graceful-degrade case lives here, not in the caller: "not published for
+// this release yet" is the ONE outcome that must not abort the install.
+export async function fetchCollectord(opts = {}) {
+  const triple = targetTriple();
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const assetName = `culpa-collectord-${triple}${exe}`;
+  const vendorDir = opts.vendorDir ?? path.join(packageRoot, "vendor");
+  const result = await fetchVerifiedAsset({
+    assetName,
+    destDir: vendorDir,
+    destName: `culpa-collectord${exe}`,
+    maxBytes: 64 * 1024 * 1024,
+    origin: opts.origin,
+    trustedHosts: opts.trustedHosts,
+    allowInsecureHttp: opts.allowInsecureHttp,
+  });
+  console.log(`getculpa: installed capture collector (${triple}, sha256 ${result.sha256.slice(0, 12)}…)`);
+  return result;
+}

package/lib/install-summary.d.mts

@@ -1,18 +1,20 @@
-import type { UpgradeClassification } from "./preflight.d.mts";
-import type { DockerState } from "./provision.d.mts";
-
-export interface InstallSummaryOptions {
-  classification: UpgradeClassification;
-  version: string;
-  previousVersion?: string | null;
-  appDir: string;
-  dockerState: DockerState;
-  imagesStaged?: boolean;
-  collectorStaged?: boolean;
-  payloadState?: "installed" | "staged" | "missing";
-  platform?: string;
-  isTTY?: boolean;
-  env?: Record<string, string | undefined>;
-}
-
-export function buildInstallSummary(opts: InstallSummaryOptions): string[];
+import type { UpgradeClassification } from "./preflight.d.mts";
+import type { DockerState } from "./provision.d.mts";
+
+export interface InstallSummaryOptions {
+  classification: UpgradeClassification;
+  version: string;
+  previousVersion?: string | null;
+  appDir: string;
+  dockerState: DockerState;
+  imagesStaged?: boolean;
+  collectorStaged?: boolean;
+  payloadState?: "installed" | "staged" | "behind" | "missing";
+  /** T-V1010-1: the versions read from updates/state.json, so the row can name them. */
+  payloadDetail?: { current: string | null; pending: string | null } | null;
+  platform?: string;
+  isTTY?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export function buildInstallSummary(opts: InstallSummaryOptions): string[];