Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

chore: verify the engine download and pin CI actions and base images (#1461)

Rohit Ghumare461a9004424f
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cbedfaa6..219caac3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,6 +38,9 @@ concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+permissions:
+ contents: read
+
jobs:
test:
runs-on: ${{ matrix.os }}
diff --git a/README.md b/README.md
index 4fa80f5e..811f8620 100644
--- a/README.md
+++ b/README.md
@@ -795,12 +795,14 @@ This starts agentmemory with a local `iii-engine` if the pinned binary is alread
Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.22.1`**, the same release as its `iii-sdk` dependency; the worker speaks that engine's wire protocol, and 0.20.0 reorganized the SDK surface, so the two move together in agentmemory releases. Override with `AGENTMEMORY_III_VERSION=<version>` if you run your own engine and know it matches.
-- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin`
- **Linux x64:** swap for `x86_64-unknown-linux-gnu`
- **Linux arm64:** swap for `aarch64-unknown-linux-gnu`
- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) and extract `iii.exe` to `%USERPROFILE%\.agentmemory\bin\iii.exe`
+Every archive has a matching `.sha256` file on the release page; when you swap the platform, use that file's hash in the check above (on Windows: `Get-FileHash`). The automatic installer in `npx @agentmemory/agentmemory` pins these hashes and refuses an archive that does not match.
+
Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.22.1`). Full docs: [iii.dev/docs](https://iii.dev/docs).
### Windows
diff --git a/deploy/coolify/Dockerfile b/deploy/coolify/Dockerfile
index c6ac809d..8a100474 100644
--- a/deploy/coolify/Dockerfile
+++ b/deploy/coolify/Dockerfile
@@ -13,6 +13,8 @@ RUN apt-get update \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
WORKDIR /opt/agentmemory
RUN [ "${III_VERSION}" = "${III_SDK_VERSION}" ] \
diff --git a/deploy/fly/Dockerfile b/deploy/fly/Dockerfile
index 4fa61c48..1a019879 100644
--- a/deploy/fly/Dockerfile
+++ b/deploy/fly/Dockerfile
@@ -13,6 +13,8 @@ RUN apt-get update \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
# `overrides` field pins iii-sdk to the exact engine release in this image
diff --git a/deploy/railway/Dockerfile b/deploy/railway/Dockerfile
index 4fa61c48..1a019879 100644
--- a/deploy/railway/Dockerfile
+++ b/deploy/railway/Dockerfile
@@ -13,6 +13,8 @@ RUN apt-get update \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
# `overrides` field pins iii-sdk to the exact engine release in this image
diff --git a/deploy/render/Dockerfile b/deploy/render/Dockerfile
index 4fa61c48..1a019879 100644
--- a/deploy/render/Dockerfile
+++ b/deploy/render/Dockerfile
@@ -13,6 +13,8 @@ RUN apt-get update \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
# `overrides` field pins iii-sdk to the exact engine release in this image
diff --git a/eval/scripts/sandbox.sh b/eval/scripts/sandbox.sh
index 7d030c2d..2cf6edee 100755
--- a/eval/scripts/sandbox.sh
+++ b/eval/scripts/sandbox.sh
@@ -14,7 +14,9 @@ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
if ! command -v iii >/dev/null 2>&1; then
echo "iii binary not on PATH. Install pinned version:"
- echo " curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin"
+ echo ' curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz'
+ echo ' echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin'
+ echo ' (other platforms: check the matching .sha256 file on the release page before extracting)'
exit 1
fi
diff --git a/package.json b/package.json
index 385cbd48..148342d0 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
"test:integration": "vitest run test/integration.test.ts",
"test:all": "vitest run",
"skills:gen": "tsx scripts/skills/generate.ts",
+ "engine:hashes": "node scripts/engine-hashes.mjs",
"skills:check": "tsx scripts/skills/generate.ts --check && tsx scripts/skills/check.ts",
"bench:load": "node --import tsx benchmark/load-100k.ts",
"eval:longmemeval": "tsx eval/runner/longmemeval.ts",
diff --git a/scripts/engine-hashes.mjs b/scripts/engine-hashes.mjs
new file mode 100644
index 00000000..a18ce811
--- /dev/null
+++ b/scripts/engine-hashes.mjs
@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const versionFile = new URL("../src/version.ts", import.meta.url);
+const installFile = new URL("../src/cli/engine-install.ts", import.meta.url);
+
+const pinned = readFileSync(versionFile, "utf8").match(/III_PINNED_VERSION = "([^"]+)"/)?.[1];
+const version = process.argv[2] ?? pinned;
+if (!version) {
+ console.error("usage: npm run engine:hashes [version]");
+ process.exit(1);
+}
+
+const assets = [
+ "iii-aarch64-apple-darwin.tar.gz",
+ "iii-x86_64-apple-darwin.tar.gz",
+ "iii-x86_64-unknown-linux-gnu.tar.gz",
+ "iii-aarch64-unknown-linux-gnu.tar.gz",
+ "iii-armv7-unknown-linux-gnueabihf.tar.gz",
+ "iii-x86_64-pc-windows-msvc.zip",
+ "iii-aarch64-pc-windows-msvc.zip",
+];
+
+async function fetchOk(url) {
+ const res = await fetch(url);
+ if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
+ return res;
+}
+
+const base = `https://github.com/iii-hq/iii/releases/download/iii/v${version}`;
+const lines = [];
+for (const asset of assets) {
+ const archive = Buffer.from(await (await fetchOk(`${base}/${asset}`)).arrayBuffer());
+ const actual = createHash("sha256").update(archive).digest("hex");
+ const published = (await (await fetchOk(`${base}/${asset.replace(/\.(tar\.gz|zip)$/, "")}.sha256`)).text()).trim().split(/\s+/)[0];
+ if (published !== actual) {
+ console.error(`${asset}: archive hashes to ${actual} but the release lists ${published}`);
+ process.exit(1);
+ }
+ console.log(`${asset} ${actual}`);
+ lines.push(` "${asset}": "${actual}",`);
+}
+
+const source = readFileSync(installFile, "utf8");
+const table = /export const III_RELEASE_SHA256: ChecksumTable = \{\n[\s\S]*?\n\};\n/;
+if (!table.test(source)) {
+ console.error("III_RELEASE_SHA256 table not found in src/cli/engine-install.ts");
+ process.exit(1);
+}
+const block = `export const III_RELEASE_SHA256: ChecksumTable = {\n "${version}": {\n${lines.join("\n")}\n },\n};\n`;
+writeFileSync(installFile, source.replace(table, block));
+console.log(`wrote hashes for iii v${version} to src/cli/engine-install.ts`);
diff --git a/src/cli.ts b/src/cli.ts
index 9ff18051..5557b696 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -56,7 +56,7 @@ import {
type RemoveOptions,
} from "./cli/remove-plan.js";
import { portFlagSuffix } from "./cli/ready-hint.js";
-import { describeInstallFailure, iiiInstallShellCommand, iiiManualInstallCommand, III_INSTALL_SPAWN_TIMEOUT_MS } from "./cli/engine-install.js";
+import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive } from "./cli/engine-install.js";
import {
dockerComposeArgs,
dockerProjectName,
@@ -1311,6 +1311,7 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
p.log.info(
`Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n` +
` 1. Download ${releaseUrl}\n` +
+ ` Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n` +
` 2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` +
`Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
);
@@ -1333,17 +1334,31 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`;
const spinner = p.spinner();
spinner.start(label);
- const result = spawnSync(
- shBin,
- ["-c", iiiInstallShellCommand(releaseUrl, binDir, binPath)],
- { stdio: "pipe", encoding: "utf-8", timeout: III_INSTALL_SPAWN_TIMEOUT_MS },
- );
- if (result.status !== 0) {
+ const outcome = installIiiArchive({
+ sh: shBin,
+ releaseUrl,
+ version: IIPINNED_VERSION,
+ asset: asset ?? "",
+ binDir,
+ binPath,
+ });
+ if (!outcome.ok) {
spinner.stop(`${label} ${pc.red("✗")}`);
+ const sha256 = expectedIiiSha256(IIPINNED_VERSION, asset ?? "");
+ const heading =
+ outcome.reason === "checksum"
+ ? "iii-engine download failed verification"
+ : outcome.reason === "no-checksum"
+ ? "iii-engine auto-install skipped"
+ : "iii-engine download failed";
+ const checksumHint = sha256
+ ? ""
+ : `Compare the archive against ${releaseUrl.replace(/\.(tar\.gz|zip)$/, ".sha256")} before extracting.\n`;
p.log.warn(
- `iii-engine download failed: ${describeInstallFailure(result).slice(0, 300)}\n` +
+ `${heading}: ${outcome.detail.slice(0, 300)}\n` +
`Install it manually, then re-run agentmemory:\n` +
- ` ${iiiManualInstallCommand(releaseUrl, binDir, binPath)}\n` +
+ ` ${iiiManualInstallCommand(releaseUrl, binDir, binPath, sha256)}\n` +
+ checksumHint +
`Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
);
return { ok: false, binPath: null };
@@ -1837,12 +1852,18 @@ async function reconcilePersistedDockerEngine(): Promise<boolean> {
function installInstructions(): string[] {
const releaseUrl = iiiReleaseUrl();
if (IS_WINDOWS) {
+ const asset = iiiReleaseAsset() ?? "";
+ const sha256 = expectedIiiSha256(IIPINNED_VERSION, asset);
+ const verify = sha256
+ ? ` Verify before extracting: (Get-FileHash .\\${asset}).Hash must be ${sha256.toUpperCase()}`
+ : ` Verify before extracting against the matching .sha256 file on the release page`;
return [
`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
"",
" A) Download the prebuilt Windows binary:",
` 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`,
` 2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`,
+ verify,
" 3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)",
" 4. Re-run: npx @agentmemory/agentmemory",
"",
@@ -1855,7 +1876,7 @@ function installInstructions(): string[] {
];
}
const linuxInstall = releaseUrl
- ? ` A) mkdir -p ~/.agentmemory/bin && curl -fsSL "${releaseUrl}" | tar -xz -C ~/.agentmemory/bin && chmod +x ~/.agentmemory/bin/iii`
+ ? ` A) ${iiiManualInstallCommand(releaseUrl, agentmemoryBinDir(), privateIiiPath(), expectedIiiSha256(IIPINNED_VERSION, iiiReleaseAsset() ?? ""))}`
: ` A) Manual download: https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`;
return [
`agentmemory needs iii-engine v${IIPINNED_VERSION}. Pick one:`,
diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts
index db1b38b4..843c1d15 100644
--- a/src/cli/engine-install.ts
+++ b/src/cli/engine-install.ts
@@ -1,32 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
export const III_INSTALL_CONNECT_TIMEOUT_S = 15;
export const III_INSTALL_MAX_TIME_S = 300;
export const III_INSTALL_SPAWN_TIMEOUT_MS =
(III_INSTALL_CONNECT_TIMEOUT_S + III_INSTALL_MAX_TIME_S + 30) * 1000;
+type ChecksumTable = Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+export const III_RELEASE_SHA256: ChecksumTable = {
+ "0.22.1": {
+ "iii-aarch64-apple-darwin.tar.gz": "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4",
+ "iii-x86_64-apple-darwin.tar.gz": "6d33940db2d3ad6a9aef9837aa5b89bf5c5e4acd0679e8178fec258af229d7e1",
+ "iii-x86_64-unknown-linux-gnu.tar.gz": "34d4bd2ec1873e6114bb836be7db9cb3f410d0d63353d240917f0bc9c30df13b",
+ "iii-aarch64-unknown-linux-gnu.tar.gz": "87efc60210c1580ef2e11b13c679a4dad91917a9d80f737c5ba7e3475b3ca413",
+ "iii-armv7-unknown-linux-gnueabihf.tar.gz": "af5dfc45149678c647e5adaca55c055428eebfa73d65884b052c30c98abcfd19",
+ "iii-x86_64-pc-windows-msvc.zip": "d862bf7cf1e864f3290c8a6fc17c308c6ecac097cb2666e4a739efc0040aae96",
+ "iii-aarch64-pc-windows-msvc.zip": "4777a48cee3fc1a742daee929e3d943df09e4ddd3357d27a33d31c9dc9e520ac",
+ },
+};
+
+export function expectedIiiSha256(
+ version: string,
+ asset: string,
+ checksums: ChecksumTable = III_RELEASE_SHA256,
+): string | null {
+ return checksums[version]?.[asset] ?? null;
+}
+
+export function sha256File(path: string): string {
+ return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
function curlTimeoutFlags(): string {
return `--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} --max-time ${III_INSTALL_MAX_TIME_S}`;
}
-export function iiiInstallShellCommand(
- releaseUrl: string,
- binDir: string,
- binPath: string,
-): string {
- const archive = `${binDir}/.iii-download.tar.gz`;
- return [
- `mkdir -p "${binDir}"`,
- `rm -f "${archive}"`,
- `if curl -fsSL ${curlTimeoutFlags()} -o "${archive}" "${releaseUrl}" && tar -xzf "${archive}" -C "${binDir}"; then rm -f "${archive}"; else code=$?; rm -f "${archive}"; exit $code; fi`,
- `chmod +x "${binPath}"`,
- ].join(" && ");
+export function iiiArchivePath(binDir: string): string {
+ return join(binDir, ".iii-download.tar.gz");
+}
+
+export function iiiDownloadShellCommand(): string {
+ return `mkdir -p "$2" && rm -f "$3" && if curl -fsSL ${curlTimeoutFlags()} -o "$3" "$1"; then :; else code=$?; rm -f "$3"; exit $code; fi`;
+}
+
+export function iiiExtractShellCommand(): string {
+ return 'if tar -xzf "$1" -C "$2"; then rm -f "$1"; else code=$?; rm -f "$1"; exit $code; fi && chmod +x "$3"';
}
export function iiiManualInstallCommand(
releaseUrl: string,
binDir: string,
binPath: string,
+ sha256: string | null,
): string {
- return `mkdir -p "${binDir}" && archive="$(mktemp "${binDir}/.iii-download.XXXXXX")" && { curl -fL --connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} -o "$archive" "${releaseUrl}" && tar -xzf "$archive" -C "${binDir}"; code=$?; rm -f "$archive"; (exit $code); } && chmod +x "${binPath}"`;
+ const verify = sha256
+ ? ` && printf '%s %s\\n' "${sha256}" "$archive" | { sha256sum -c - 2>/dev/null || shasum -a 256 -c -; }`
+ : "";
+ return `mkdir -p "${binDir}" && archive="$(mktemp "${binDir}/.iii-download.XXXXXX")" && { curl -fL --connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} -o "$archive" "${releaseUrl}"${verify} && tar -xzf "$archive" -C "${binDir}"; code=$?; rm -f "$archive"; (exit $code); } && chmod +x "${binPath}"`;
}
export function describeInstallFailure(result: {
@@ -48,3 +81,62 @@ export function describeInstallFailure(result: {
if (result.error) return result.error.message;
return `installer exited with status ${result.status ?? "unknown"}`;
}
+
+export type IiiInstallOutcome =
+ | { ok: true }
+ | { ok: false; reason: "no-checksum" | "download" | "checksum" | "extract"; detail: string };
+
+export function installIiiArchive(opts: {
+ sh: string;
+ releaseUrl: string;
+ version: string;
+ asset: string;
+ binDir: string;
+ binPath: string;
+ env?: NodeJS.ProcessEnv;
+ checksums?: ChecksumTable;
+}): IiiInstallOutcome {
+ const expected = expectedIiiSha256(opts.version, opts.asset, opts.checksums);
+ if (!expected) {
+ return {
+ ok: false,
+ reason: "no-checksum",
+ detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`,
+ };
+ }
+ const run = (script: string, args: string[]) =>
+ spawnSync(opts.sh, ["-c", script, "sh", ...args], {
+ stdio: "pipe",
+ encoding: "utf-8",
+ timeout: III_INSTALL_SPAWN_TIMEOUT_MS,
+ env: opts.env ?? process.env,
+ });
+
+ const archive = iiiArchivePath(opts.binDir);
+ const download = run(iiiDownloadShellCommand(), [opts.releaseUrl, opts.binDir, archive]);
+ if (download.status !== 0) {
+ return { ok: false, reason: "download", detail: describeInstallFailure(download) };
+ }
+
+ let actual: string;
+ try {
+ actual = sha256File(archive);
+ } catch (err) {
+ rmSync(archive, { force: true });
+ return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) };
+ }
+ if (actual !== expected) {
+ rmSync(archive, { force: true });
+ return {
+ ok: false,
+ reason: "checksum",
+ detail: `SHA-256 mismatch for ${opts.asset}: expected ${expected}, got ${actual}. The download was deleted and nothing was installed`,
+ };
+ }
+
+ const extract = run(iiiExtractShellCommand(), [archive, opts.binDir, opts.binPath]);
+ if (extract.status !== 0) {
+ return { ok: false, reason: "extract", detail: describeInstallFailure(extract) };
+ }
+ return { ok: true };
+}
diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts
index 04fb4605..c02e4158 100644
--- a/test/engine-install.test.ts
+++ b/test/engine-install.test.ts
@@ -6,11 +6,17 @@ import { afterEach, describe, expect, it } from "vitest";
import {
III_INSTALL_CONNECT_TIMEOUT_S,
III_INSTALL_MAX_TIME_S,
+ III_RELEASE_SHA256,
describeInstallFailure,
- iiiInstallShellCommand,
+ expectedIiiSha256,
+ iiiDownloadShellCommand,
iiiManualInstallCommand,
+ installIiiArchive,
+ sha256File,
} from "../src/cli/engine-install.js";
+import { III_PINNED_VERSION } from "../src/version.js";
+const ASSET = "iii-x86_64-unknown-linux-gnu.tar.gz";
const sandboxes: string[] = [];
function sandbox(): string {
@@ -32,66 +38,171 @@ function fakeCurl(dir: string, script: string): string {
return bin;
}
-function runInstall(dir: string, bin: string) {
+function buildTarball(dir: string): string {
+ const staging = join(dir, "staging");
+ mkdirSync(staging);
+ writeFileSync(join(staging, "iii"), "#!/bin/sh\necho iii\n");
+ const tarball = join(dir, "iii.tar.gz");
+ spawnSync("tar", ["-czf", tarball, "-C", staging, "iii"]);
+ return tarball;
+}
+
+function curlServing(dir: string, tarball: string): string {
+ return fakeCurl(
+ dir,
+ `out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; cp "${tarball}" "$out"`,
+ );
+}
+
+function runInstall(dir: string, bin: string, sha256: string | null, asset = ASSET) {
const binDir = join(dir, "bin");
const binPath = join(binDir, "iii");
- const result = spawnSync(
- "sh",
- ["-c", iiiInstallShellCommand("https://example.invalid/iii.tar.gz", binDir, binPath)],
- { encoding: "utf-8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } },
- );
- return { result, binDir, binPath };
+ const checksums = sha256 ? { "9.9.9": { [ASSET]: sha256 } } : {};
+ const outcome = installIiiArchive({
+ sh: "sh",
+ releaseUrl: "https://example.invalid/iii.tar.gz",
+ version: "9.9.9",
+ asset,
+ binDir,
+ binPath,
+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
+ checksums,
+ });
+ return { outcome, binDir, binPath };
}
describe("iii engine auto-installer", () => {
it("passes connect and overall timeouts to curl", () => {
- const cmd = iiiInstallShellCommand("https://x/iii.tar.gz", "/b", "/b/iii");
+ const cmd = iiiDownloadShellCommand();
expect(cmd).toContain(`--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S}`);
expect(cmd).toContain(`--max-time ${III_INSTALL_MAX_TIME_S}`);
});
+ it("pins a SHA-256 for every auto-installable asset of the pinned engine release", () => {
+ const pinned = III_RELEASE_SHA256[III_PINNED_VERSION];
+ expect(pinned).toBeDefined();
+ for (const asset of [
+ "iii-aarch64-apple-darwin.tar.gz",
+ "iii-x86_64-apple-darwin.tar.gz",
+ "iii-x86_64-unknown-linux-gnu.tar.gz",
+ "iii-aarch64-unknown-linux-gnu.tar.gz",
+ "iii-armv7-unknown-linux-gnueabihf.tar.gz",
+ "iii-x86_64-pc-windows-msvc.zip",
+ "iii-aarch64-pc-windows-msvc.zip",
+ ]) {
+ expect(expectedIiiSha256(III_PINNED_VERSION, asset)).toMatch(/^[0-9a-f]{64}$/);
+ }
+ });
+
it("leaves no partial binary or archive behind when the download times out", () => {
const dir = sandbox();
const bin = fakeCurl(
dir,
'out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; printf partial > "$out"; echo "curl: (28) Operation timed out" >&2; exit 28',
);
- const { result, binDir, binPath } = runInstall(dir, bin);
+ const { outcome, binDir, binPath } = runInstall(dir, bin, "0".repeat(64));
- expect(result.status).toBe(28);
+ expect(outcome.ok).toBe(false);
+ if (!outcome.ok) {
+ expect(outcome.reason).toBe("download");
+ expect(outcome.detail).toContain("timed out");
+ }
expect(existsSync(binPath)).toBe(false);
expect(readdirSync(binDir)).toEqual([]);
- expect(describeInstallFailure(result)).toContain("timed out");
});
- it("installs the binary when the download completes", () => {
+ it("installs the binary when the download matches the pinned SHA-256", () => {
const dir = sandbox();
- const staging = join(dir, "staging");
- mkdirSync(staging);
- writeFileSync(join(staging, "iii"), "#!/bin/sh\necho iii\n");
- const tarball = join(dir, "iii.tar.gz");
- spawnSync("tar", ["-czf", tarball, "-C", staging, "iii"]);
- const bin = fakeCurl(
- dir,
- `out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; cp "${tarball}" "$out"`,
- );
- const { result, binDir, binPath } = runInstall(dir, bin);
+ const tarball = buildTarball(dir);
+ const { outcome, binDir, binPath } = runInstall(dir, curlServing(dir, tarball), sha256File(tarball));
- expect(result.status).toBe(0);
+ expect(outcome).toEqual({ ok: true });
expect(existsSync(binPath)).toBe(true);
expect(readdirSync(binDir)).toEqual(["iii"]);
});
- it("explains a timeout without stderr and prints a copyable manual command", () => {
+ it("refuses to extract a download whose SHA-256 does not match", () => {
+ const dir = sandbox();
+ const tarball = buildTarball(dir);
+ const wrong = "f".repeat(64);
+ const { outcome, binDir, binPath } = runInstall(dir, curlServing(dir, tarball), wrong);
+
+ expect(outcome.ok).toBe(false);
+ if (!outcome.ok) {
+ expect(outcome.reason).toBe("checksum");
+ expect(outcome.detail).toContain(`expected ${wrong}`);
+ expect(outcome.detail).toContain(`got ${sha256File(tarball)}`);
+ }
+ expect(existsSync(binPath)).toBe(false);
+ expect(readdirSync(binDir)).toEqual([]);
+ });
+
+ it("passes paths to the shell as arguments, never as script text", () => {
+ const dir = sandbox();
+ const tarball = buildTarball(dir);
+ const tricky = join(dir, 'odd $(touch pwned) "dir"');
+ const binPath = join(tricky, "iii");
+ const outcome = installIiiArchive({
+ sh: "sh",
+ releaseUrl: "https://example.invalid/iii.tar.gz",
+ version: "9.9.9",
+ asset: ASSET,
+ binDir: tricky,
+ binPath,
+ env: { ...process.env, PATH: `${curlServing(dir, tarball)}:${process.env.PATH}` },
+ checksums: { "9.9.9": { [ASSET]: sha256File(tarball) } },
+ });
+
+ expect(outcome).toEqual({ ok: true });
+ expect(existsSync(binPath)).toBe(true);
+ expect(existsSync(join(process.cwd(), "pwned"))).toBe(false);
+ expect(iiiDownloadShellCommand()).not.toContain(dir);
+ });
+
+ it("does not download anything for a platform or version without a pinned SHA-256", () => {
+ const dir = sandbox();
+ const bin = fakeCurl(dir, `touch "${join(dir, "curl-called")}"; exit 1`);
+ const { outcome, binDir } = runInstall(dir, bin, null, "iii-riscv64-unknown-linux-gnu.tar.gz");
+
+ expect(outcome.ok).toBe(false);
+ if (!outcome.ok) expect(outcome.reason).toBe("no-checksum");
+ expect(existsSync(join(dir, "curl-called"))).toBe(false);
+ expect(existsSync(binDir)).toBe(false);
+ expect(expectedIiiSha256(III_PINNED_VERSION, "iii-riscv64-unknown-linux-gnu.tar.gz")).toBeNull();
+ });
+
+ it("explains a timeout without stderr and prints a copyable manual command that verifies the archive", () => {
expect(describeInstallFailure({ status: 28, stderr: "" })).toContain("download timed out");
expect(
describeInstallFailure({ status: null, error: Object.assign(new Error("x"), { code: "ETIMEDOUT" }) }),
).toContain("timed out after");
- const manual = iiiManualInstallCommand("https://x/iii.tar.gz", "/b", "/b/iii");
- expect(manual).toContain('curl -fL --connect-timeout');
+ const sha = "a".repeat(64);
+ const manual = iiiManualInstallCommand("https://x/iii.tar.gz", "/b", "/b/iii", sha);
+ expect(manual).toContain("curl -fL --connect-timeout");
expect(manual).toContain('chmod +x "/b/iii"');
expect(manual).toContain('mktemp "/b/.iii-download.XXXXXX"');
expect(manual).not.toContain("/tmp/");
expect(manual).toContain('rm -f "$archive"; (exit $code)');
+ expect(manual).toContain(sha);
+ expect(manual.indexOf(sha)).toBeLessThan(manual.indexOf("tar -xzf"));
+ expect(iiiManualInstallCommand("https://x/iii.tar.gz", "/b", "/b/iii", null)).not.toContain("sha256sum");
+ });
+
+ it("the manual command stops before extraction when the checksum does not match", () => {
+ const dir = sandbox();
+ const tarball = buildTarball(dir);
+ const bin = curlServing(dir, tarball);
+ const binDir = join(dir, "manual");
+ const binPath = join(binDir, "iii");
+ const run = (sha: string) =>
+ spawnSync("sh", ["-c", iiiManualInstallCommand("https://example.invalid/iii.tar.gz", binDir, binPath, sha)], {
+ encoding: "utf-8",
+ env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
+ });
+
+ expect(run("e".repeat(64)).status).not.toBe(0);
+ expect(existsSync(binPath)).toBe(false);
+ expect(run(sha256File(tarball)).status).toBe(0);
+ expect(existsSync(binPath)).toBe(true);
});
});