Add managed install checksum helpers

Refs #10

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>

Author: SebTardif

README.md

@@ -19,6 +19,16 @@ Managed binary downloads, MCP config injection, and marketplace publishing workf
 
 The extension now has managed-install groundwork for release asset targeting and status reporting, using VS Code global storage for future managed binaries, but it does not download binaries yet.
 
+## Managed install security model
+
+The managed installer work is intentionally conservative:
+
+- downloads must come from `https://github.com/patchloom/patchloom/releases/download/...`
+- each downloaded archive must match a published SHA-256 checksum before the extension can trust it
+- checksum verification failures must stop the install before any managed binary is used
+- a failed verification or failed install must not replace an already working Patchloom binary
+- verification failures should stay diagnosable through explicit user-facing status and error messages
+
 ## Commands
 
 - `Patchloom: Show Status`

src/install/managed.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import * as path from "node:path";
 
 export const PATCHLOOM_RELEASE_REPO = "patchloom/patchloom";
@@ -54,6 +55,27 @@ export interface ManagedInstallStatusInputs {
   readonly fileExists?: (filePath: string) => Promise<boolean>;
 }
 
+export interface ManagedInstallChecksumEntry {
+  readonly fileName: string;
+  readonly sha256: string;
+}
+
+export type ManagedInstallVerificationFailureReason =
+  | "missing-checksum"
+  | "invalid-checksum-format"
+  | "checksum-mismatch"
+  | "untrusted-download-url";
+
+export class ManagedInstallVerificationError extends Error {
+  readonly reason: ManagedInstallVerificationFailureReason;
+
+  constructor(reason: ManagedInstallVerificationFailureReason, message: string) {
+    super(message);
+    this.name = "ManagedInstallVerificationError";
+    this.reason = reason;
+  }
+}
+
 export function setManagedInstallRoot(root: string | undefined): void {
   managedInstallRoot = root;
 }
@@ -149,6 +171,97 @@ export function buildManagedInstallReleaseAssets(
   };
 }
 
+export function parseManagedInstallChecksumFile(content: string): ManagedInstallChecksumEntry[] {
+  const entries: ManagedInstallChecksumEntry[] = [];
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+
+    const match = line.match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (!match) {
+      throw new ManagedInstallVerificationError(
+        "invalid-checksum-format",
+        `Invalid checksum line: ${rawLine}`
+      );
+    }
+
+    entries.push({
+      sha256: match[1].toLowerCase(),
+      fileName: match[2].trim()
+    });
+  }
+
+  return entries;
+}
+
+export function resolveManagedInstallChecksum(
+  checksumFileContent: string,
+  archiveFileName: string
+): string {
+  const entry = parseManagedInstallChecksumFile(checksumFileContent)
+    .find((candidate) => candidate.fileName === archiveFileName);
+
+  if (!entry) {
+    throw new ManagedInstallVerificationError(
+      "missing-checksum",
+      `Missing checksum entry for ${archiveFileName}.`
+    );
+  }
+
+  return entry.sha256;
+}
+
+export function calculateSha256Hex(content: string | Uint8Array): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export function verifyManagedInstallArchiveChecksum(
+  archiveContent: string | Uint8Array,
+  checksumFileContent: string,
+  archiveFileName: string
+): string {
+  const expectedSha256 = resolveManagedInstallChecksum(checksumFileContent, archiveFileName);
+  const actualSha256 = calculateSha256Hex(archiveContent);
+
+  if (expectedSha256 !== actualSha256) {
+    throw new ManagedInstallVerificationError(
+      "checksum-mismatch",
+      `Checksum mismatch for ${archiveFileName}. Expected ${expectedSha256}, got ${actualSha256}.`
+    );
+  }
+
+  return actualSha256;
+}
+
+export function isTrustedManagedInstallDownloadUrl(
+  url: string,
+  repo = PATCHLOOM_RELEASE_REPO
+): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:"
+      && parsed.hostname === "github.com"
+      && parsed.pathname.startsWith(`/${repo}/releases/download/`);
+  } catch {
+    return false;
+  }
+}
+
+export function assertTrustedManagedInstallDownloadUrl(
+  url: string,
+  repo = PATCHLOOM_RELEASE_REPO
+): void {
+  if (!isTrustedManagedInstallDownloadUrl(url, repo)) {
+    throw new ManagedInstallVerificationError(
+      "untrusted-download-url",
+      `Managed install downloads must come from https://github.com/${repo}/releases/download/.`
+    );
+  }
+}
+
 export async function inspectManagedInstallStatus(
   inputs: ManagedInstallStatusInputs
 ): Promise<ManagedInstallStatus | undefined> {

test/unit/binary.test.ts

@@ -9,12 +9,18 @@ import {
   resolvePatchloomStatusWithInputs
 } from "../../src/binary/patchloom";
 import {
+  assertTrustedManagedInstallDownloadUrl,
   buildManagedInstallReleaseAssets,
+  calculateSha256Hex,
   detectManagedInstallTarget,
   inspectManagedInstallStatus,
+  ManagedInstallVerificationError,
   normalizeReleaseVersion,
+  parseManagedInstallChecksumFile,
   PATCHLOOM_MANAGED_INSTALL_DIR,
-  resolveManagedInstallPaths
+  resolveManagedInstallChecksum,
+  resolveManagedInstallPaths,
+  verifyManagedInstallArchiveChecksum
 } from "../../src/install/managed";
 import { resolveMcpTargets } from "../../src/mcp/config";
 import { defaultWorkspaceFolderIndex, describeWorkspaceEnvironment } from "../../src/workspace/readiness";
@@ -163,6 +169,90 @@ test("buildManagedInstallReleaseAssets builds archive and checksum urls", () =>
   assert.match(release.checksumDownloadUrl, /patchloom-x86_64-unknown-linux-gnu\.tar\.xz\.sha256$/);
 });
 
+test("parseManagedInstallChecksumFile accepts common sha256 sidecar formats", () => {
+  const entries = parseManagedInstallChecksumFile([
+    "ece89100861aa6d4c7e409f279777d1619f8d86e0f67f396fa9f3e4535eb2f0e  patchloom-aarch64-apple-darwin.tar.xz",
+    "1dc508c14f9b3584c992c61dcf8d18d8d3a6770f33fff241038c1e9ea7b27a97 *patchloom-x86_64-unknown-linux-gnu.tar.xz"
+  ].join("\n"));
+
+  assert.deepEqual(entries, [
+    {
+      sha256: "ece89100861aa6d4c7e409f279777d1619f8d86e0f67f396fa9f3e4535eb2f0e",
+      fileName: "patchloom-aarch64-apple-darwin.tar.xz"
+    },
+    {
+      sha256: "1dc508c14f9b3584c992c61dcf8d18d8d3a6770f33fff241038c1e9ea7b27a97",
+      fileName: "patchloom-x86_64-unknown-linux-gnu.tar.xz"
+    }
+  ]);
+});
+
+test("resolveManagedInstallChecksum returns the matching archive checksum", () => {
+  const checksum = resolveManagedInstallChecksum(
+    [
+      "ece89100861aa6d4c7e409f279777d1619f8d86e0f67f396fa9f3e4535eb2f0e  patchloom-aarch64-apple-darwin.tar.xz",
+      "1dc508c14f9b3584c992c61dcf8d18d8d3a6770f33fff241038c1e9ea7b27a97  patchloom-x86_64-unknown-linux-gnu.tar.xz"
+    ].join("\n"),
+    "patchloom-x86_64-unknown-linux-gnu.tar.xz"
+  );
+
+  assert.equal(checksum, "1dc508c14f9b3584c992c61dcf8d18d8d3a6770f33fff241038c1e9ea7b27a97");
+});
+
+test("verifyManagedInstallArchiveChecksum validates archive content against the checksum sidecar", () => {
+  const checksum = verifyManagedInstallArchiveChecksum(
+    "patchloom",
+    "ece89100861aa6d4c7e409f279777d1619f8d86e0f67f396fa9f3e4535eb2f0e  patchloom-aarch64-apple-darwin.tar.xz",
+    "patchloom-aarch64-apple-darwin.tar.xz"
+  );
+
+  assert.equal(checksum, calculateSha256Hex("patchloom"));
+});
+
+test("verifyManagedInstallArchiveChecksum rejects mismatched archive content", () => {
+  assert.throws(
+    () => verifyManagedInstallArchiveChecksum(
+      "managed-install",
+      "ece89100861aa6d4c7e409f279777d1619f8d86e0f67f396fa9f3e4535eb2f0e  patchloom-aarch64-apple-darwin.tar.xz",
+      "patchloom-aarch64-apple-darwin.tar.xz"
+    ),
+    (error: unknown) => {
+      assert.ok(error instanceof ManagedInstallVerificationError);
+      assert.equal(error.reason, "checksum-mismatch");
+      assert.match(error.message, /checksum mismatch/i);
+      return true;
+    }
+  );
+});
+
+test("parseManagedInstallChecksumFile rejects invalid lines", () => {
+  assert.throws(
+    () => parseManagedInstallChecksumFile("not-a-checksum patchloom-aarch64-apple-darwin.tar.xz"),
+    (error: unknown) => {
+      assert.ok(error instanceof ManagedInstallVerificationError);
+      assert.equal(error.reason, "invalid-checksum-format");
+      return true;
+    }
+  );
+});
+
+test("assertTrustedManagedInstallDownloadUrl only accepts GitHub release download urls", () => {
+  assert.doesNotThrow(() => assertTrustedManagedInstallDownloadUrl(
+    "https://github.com/patchloom/patchloom/releases/download/v0.1.0/patchloom-aarch64-apple-darwin.tar.xz"
+  ));
+
+  assert.throws(
+    () => assertTrustedManagedInstallDownloadUrl(
+      "https://example.com/patchloom-aarch64-apple-darwin.tar.xz"
+    ),
+    (error: unknown) => {
+      assert.ok(error instanceof ManagedInstallVerificationError);
+      assert.equal(error.reason, "untrusted-download-url");
+      return true;
+    }
+  );
+});
+
 test("managed install constants use a stable storage directory name", () => {
   assert.equal(PATCHLOOM_MANAGED_INSTALL_DIR, "patchloom-managed");
 });