@jsorm/cli 0.2.0 → 0.2.1

package/README.md

@@ -60,8 +60,25 @@ jsorm watch
 
 ---
 
+## jsorm update
+
+Installs the latest engine compatible with this CLI and removes older installed versions. It checks the download server now and fails, removing nothing, when the server cannot be reached or the latest engine belongs to a newer release line.
+
+```bash
+jsorm update            # install the latest compatible engine
+jsorm update --check    # report installed and latest, install nothing
+jsorm update --force    # reinstall the latest compatible engine
+```
+
+The engine lives in `~/.jsorm/engines/v<version>/` (owner-only). Before every run the CLI checks the binary against the SHA-256 signed in the release manifest; a modified engine is reinstalled, never run. Other commands check for updates at most once every 24 hours; `JSORM_NO_UPDATE_CHECK=1` skips the check while an engine is installed.
+
+---
+
 ## Requirements
 
 - Node.js 22+
+- macOS or Linux, x64 or arm64 (Windows is not supported yet)
 - `jsorm.config.ts` at project root
-- Models in configured path
+- Models in configured path
+
+Run commands through your package manager: `pnpm jsorm`, `npx jsorm`, `yarn jsorm` or `bunx jsorm`. A local install does not put `jsorm` on `PATH`.

package/dist/index.mjs

@@ -43,6 +43,15 @@ function detectPackageManager() {
 	if (process.env.npm_config_user_agent?.includes("yarn")) return "yarn";
 	return "npm";
 }
+/** Command that runs a locally installed `jsorm` with this package manager. */
+function cliRunner(pm) {
+	switch (pm) {
+		case "npm": return "npx jsorm";
+		case "yarn": return "yarn jsorm";
+		case "bun": return "bunx jsorm";
+		default: return "pnpm jsorm";
+	}
+}
 function detectRuntime() {
 	if (typeof process !== "undefined" && process.versions?.bun) return "bun";
 	if (typeof process !== "undefined" && process.versions?.deno) return "deno";
@@ -85,76 +94,6 @@ function detectFramework() {
 	return "none";
 }
 //#endregion
-//#region src/manifest.ts
-const EMBEDDED_PUBLIC_KEY_B64 = "6AUQMvF7jBV+S8yv9K8hnnoYzIznQw4nf5x5LAuEsfM=";
-function getSpkiPublicKey(rawKeyB64 = EMBEDDED_PUBLIC_KEY_B64) {
-	const rawKey = Buffer.from(rawKeyB64, "base64");
-	const spkiDer = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), rawKey]);
-	return createPublicKey({
-		key: spkiDer,
-		format: "der",
-		type: "spki"
-	});
-}
-function invalid(reason) {
-	return {
-		status: "invalid",
-		reason
-	};
-}
-/**
-* Verifies the envelope `{ success, signature, signed_payload }` and returns
-* the manifest decoded from `signed_payload`, the exact bytes that were signed.
-* The unsigned `envelope.manifest` copy is never trusted.
-*/
-function parseSignedEnvelope(envelope, publicKey) {
-	if (!envelope || typeof envelope !== "object") return invalid("Invalid manifest response");
-	const { success, signature, signed_payload } = envelope;
-	if (success !== true) return invalid("Invalid manifest response");
-	if (typeof signature !== "string" || typeof signed_payload !== "string") return invalid("Manifest signature or signed payload missing. Refusing to continue without signature verification.");
-	const sigBytes = Buffer.from(signature, "base64");
-	if (sigBytes.length !== 64) return invalid(`Invalid signature length: ${sigBytes.length} (expected 64)`);
-	const signedBytes = Buffer.from(signed_payload, "base64");
-	let valid = false;
-	try {
-		valid = verify(null, signedBytes, publicKey, sigBytes);
-	} catch {}
-	if (!valid) return invalid("Manifest signature verification failed. The manifest may have been tampered with.");
-	let manifest;
-	try {
-		manifest = JSON.parse(signedBytes.toString("utf-8"));
-	} catch {
-		return invalid("Signed manifest is not valid JSON");
-	}
-	if (typeof manifest?.version !== "string" || !manifest.targets || typeof manifest.targets !== "object") return invalid("Invalid manifest format");
-	return {
-		status: "ok",
-		manifest
-	};
-}
-async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
-	let res;
-	try {
-		res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
-	} catch (err) {
-		return {
-			status: "unreachable",
-			reason: `Manifest fetch error: ${err instanceof Error ? err.message : err}`
-		};
-	}
-	if (!res.ok) return {
-		status: "unreachable",
-		reason: `Manifest fetch failed: ${res.status} ${res.statusText}`
-	};
-	let envelope;
-	try {
-		envelope = await res.json();
-	} catch {
-		return invalid("Invalid manifest response");
-	}
-	return parseSignedEnvelope(envelope, publicKey);
-}
-//#endregion
 //#region src/version.ts
 function compareVersions(a, b) {
 	const pa = a.split(".").map(Number);
@@ -181,6 +120,22 @@ function isCompatibleEngine(cliVersion, engineVersion) {
 function getVersionDir(enginesDir, version) {
 	return join(enginesDir, `v${version}`);
 }
+/** Signed envelope stored next to an installed binary. */
+function getEnvelopePath(enginesDir, version, binaryName) {
+	return join(getVersionDir(enginesDir, version), `${binaryName}.envelope.json`);
+}
+/**
+* Creates `dir` (and missing parents) readable and writable by its owner
+* only, and tightens it when it already exists: nobody else may replace an
+* engine the CLI is going to run.
+*/
+function ensureOwnerOnlyDir(dir) {
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	if (process.platform !== "win32") chmodSync(dir, 448);
+}
 /** Installed versions that hold `binaryName`, newest first, e.g. ["0.2.1", "0.2.0"]. */
 function listInstalledVersions(enginesDir, binaryName) {
 	if (!existsSync(enginesDir)) return [];
@@ -229,8 +184,8 @@ function extractTarGz(tarPath, destDir) {
 * Returns the installed binary path.
 */
 async function installEngine(options) {
-	const { url, enginesDir, version, binaryName, expectedSha256, log = () => {} } = options;
-	mkdirSync(enginesDir, { recursive: true });
+	const { url, enginesDir, version, binaryName, expectedSha256, expectedBinarySha256, envelope, log = () => {} } = options;
+	ensureOwnerOnlyDir(enginesDir);
 	const tempDir = mkdtempSync(join(enginesDir, ".tmp-"));
 	try {
 		const tarPath = join(tempDir, "engine.tar.gz");
@@ -247,10 +202,15 @@ async function installEngine(options) {
 		extractTarGz(tarPath, extractDir);
 		const extractedPath = join(extractDir, "jsorm");
 		if (!existsSync(extractedPath)) throw new Error(`Archive does not contain the "jsorm" binary`);
-		if (process.platform !== "win32") chmodSync(extractedPath, 493);
+		const binaryHash = await sha256File(extractedPath);
+		if (binaryHash !== expectedBinarySha256) throw new Error(`Binary checksum mismatch!\n  Expected: ${expectedBinarySha256}\n  Got:      ${binaryHash}`);
+		if (process.platform !== "win32") chmodSync(extractedPath, 448);
+		const envelopeTemp = join(tempDir, "envelope.json");
+		writeFileSync(envelopeTemp, JSON.stringify(envelope), { mode: 384 });
 		const destDir = getVersionDir(enginesDir, version);
 		const destPath = join(destDir, binaryName);
-		mkdirSync(destDir, { recursive: true });
+		ensureOwnerOnlyDir(destDir);
+		renameSync(envelopeTemp, getEnvelopePath(enginesDir, version, binaryName));
 		renameSync(extractedPath, destPath);
 		log(`  ✓ Engine installed: ${destPath}`);
 		return destPath;
@@ -262,6 +222,124 @@ async function installEngine(options) {
 	}
 }
 //#endregion
+//#region src/manifest.ts
+const EMBEDDED_PUBLIC_KEY_B64 = "6AUQMvF7jBV+S8yv9K8hnnoYzIznQw4nf5x5LAuEsfM=";
+function getSpkiPublicKey(rawKeyB64 = EMBEDDED_PUBLIC_KEY_B64) {
+	const rawKey = Buffer.from(rawKeyB64, "base64");
+	const spkiDer = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), rawKey]);
+	return createPublicKey({
+		key: spkiDer,
+		format: "der",
+		type: "spki"
+	});
+}
+function invalid(reason) {
+	return {
+		status: "invalid",
+		reason
+	};
+}
+/**
+* Verifies the envelope `{ success, signature, signed_payload }` and returns
+* the manifest decoded from `signed_payload`, the exact bytes that were signed.
+* The unsigned `envelope.manifest` copy is never trusted.
+*/
+function parseSignedEnvelope(envelope, publicKey) {
+	if (!envelope || typeof envelope !== "object") return invalid("Invalid manifest response");
+	const { success, signature, signed_payload } = envelope;
+	if (success !== true) return invalid("Invalid manifest response");
+	if (typeof signature !== "string" || typeof signed_payload !== "string") return invalid("Manifest signature or signed payload missing. Refusing to continue without signature verification.");
+	const sigBytes = Buffer.from(signature, "base64");
+	if (sigBytes.length !== 64) return invalid(`Invalid signature length: ${sigBytes.length} (expected 64)`);
+	const signedBytes = Buffer.from(signed_payload, "base64");
+	let valid = false;
+	try {
+		valid = verify(null, signedBytes, publicKey, sigBytes);
+	} catch {}
+	if (!valid) return invalid("Manifest signature verification failed. The manifest may have been tampered with.");
+	let manifest;
+	try {
+		manifest = JSON.parse(signedBytes.toString("utf-8"));
+	} catch {
+		return invalid("Signed manifest is not valid JSON");
+	}
+	if (typeof manifest?.version !== "string" || !manifest.targets || typeof manifest.targets !== "object") return invalid("Invalid manifest format");
+	return {
+		status: "ok",
+		manifest,
+		envelope: {
+			success: true,
+			signature,
+			signed_payload
+		}
+	};
+}
+async function fetchManifest(url, publicKey = getSpkiPublicKey()) {
+	let res;
+	try {
+		res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+	} catch (err) {
+		return {
+			status: "unreachable",
+			reason: `Manifest fetch error: ${err instanceof Error ? err.message : err}`
+		};
+	}
+	if (!res.ok) return {
+		status: "unreachable",
+		reason: `Manifest fetch failed: ${res.status} ${res.statusText}`
+	};
+	let envelope;
+	try {
+		envelope = await res.json();
+	} catch {
+		return invalid("Invalid manifest response");
+	}
+	return parseSignedEnvelope(envelope, publicKey);
+}
+//#endregion
+//#region src/verify.ts
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/**
+* Checks an installed engine before it runs: its stored envelope must be
+* signed with `publicKey`, declare this version and target, and carry the
+* SHA-256 of the binary on disk.
+*/
+async function verifyInstalledEngine(enginesDir, version, binaryName, publicKey) {
+	const envelopePath = getEnvelopePath(enginesDir, version, binaryName);
+	if (!existsSync(envelopePath)) return {
+		ok: false,
+		reason: "no signed envelope next to the binary"
+	};
+	let envelope;
+	try {
+		envelope = JSON.parse(readFileSync(envelopePath, "utf-8"));
+	} catch {
+		return {
+			ok: false,
+			reason: "the stored envelope is not valid JSON"
+		};
+	}
+	const result = parseSignedEnvelope(envelope, publicKey);
+	if (result.status !== "ok") return {
+		ok: false,
+		reason: result.reason
+	};
+	if (result.manifest.version !== version) return {
+		ok: false,
+		reason: `the stored envelope is for v${result.manifest.version}`
+	};
+	const expected = result.manifest.targets[binaryName]?.binary_sha256;
+	if (typeof expected !== "string" || !SHA256_HEX.test(expected)) return {
+		ok: false,
+		reason: `the stored envelope has no binary_sha256 for ${binaryName}`
+	};
+	if (await sha256File(join(getVersionDir(enginesDir, version), binaryName)) !== expected) return {
+		ok: false,
+		reason: "the binary does not match its signed SHA-256"
+	};
+	return { ok: true };
+}
+//#endregion
 //#region src/resolve.ts
 const DAY_MS = 864e5;
 const LAST_CHECK_FILE = ".last-check";
@@ -290,19 +368,40 @@ async function fetchTrustedManifest(options) {
 	if (result.status === "invalid") throw new Error(result.reason);
 	log(`  ✓ Manifest signature verified`);
 	log(`  ✓ Manifest v${result.manifest.version} (${Object.keys(result.manifest.targets).length} targets)`);
-	return result.manifest;
+	return {
+		manifest: result.manifest,
+		envelope: result.envelope
+	};
 }
 /**
 * Returns the path of an engine binary that is safe to run: the installed one
 * when it is current, or a freshly installed stable release. Only engines of
-* the CLI's release line are used. When the server cannot be reached, an
-* installed engine is used as is. Throws when no engine can be provided or
-* when the server's answer cannot be trusted.
+* the CLI's release line are used, and an installed engine only runs after
+* its binary matches the signed SHA-256 stored next to it. When the server
+* cannot be reached, a verified installed engine is used as is. Throws when
+* no engine can be provided or when the server's answer cannot be trusted.
 */
 async function resolveEngine(options) {
-	const { enginesDir, binaryName, downloadUrl, cliVersion, log = () => {}, checkIntervalMs = DAY_MS, skipUpdateCheck = false, force = false, requireLiveCheck = false, now = Date.now } = options;
+	const { enginesDir, binaryName, downloadUrl, cliVersion, publicKey = getSpkiPublicKey(), log = () => {}, updateCommand = "jsorm update", checkIntervalMs = DAY_MS, skipUpdateCheck = false, force = false, requireLiveCheck = false, now = Date.now } = options;
 	const compatible = (version) => isCompatibleEngine(cliVersion, version);
-	const installedVer = detectInstalledVersion(enginesDir, binaryName, compatible);
+	let installedVer = detectInstalledVersion(enginesDir, binaryName, compatible);
+	let rejectedVer = null;
+	if (installedVer) {
+		const check = await verifyInstalledEngine(enginesDir, installedVer, binaryName, publicKey);
+		if (!check.ok) {
+			log(`  ⚠ Installed engine v${installedVer} failed verification: ${check.reason}`);
+			try {
+				rmSync(getVersionDir(enginesDir, installedVer), {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				log(`  ⚠ Could not remove engine v${installedVer}: ${err instanceof Error ? err.message : err}`);
+			}
+			rejectedVer = installedVer;
+			installedVer = null;
+		}
+	}
 	const installedPath = installedVer ? join(getVersionDir(enginesDir, installedVer), binaryName) : null;
 	if (installedPath && !force && !requireLiveCheck) {
 		if (skipUpdateCheck) return installedPath;
@@ -310,15 +409,20 @@ async function resolveEngine(options) {
 		const elapsed = lastCheck === null ? Infinity : now() - lastCheck;
 		if (checkIntervalMs > 0 && elapsed >= 0 && elapsed < checkIntervalMs) return installedPath;
 	}
-	const manifest = await fetchTrustedManifest(options);
-	if ("unreachable" in manifest) {
+	const trusted = await fetchTrustedManifest({
+		...options,
+		publicKey
+	});
+	if ("unreachable" in trusted) {
 		if (installedPath && !requireLiveCheck) {
-			log(`  ⚠ ${manifest.unreachable}`);
+			log(`  ⚠ ${trusted.unreachable}`);
 			log(`  ⚠ Using installed engine v${installedVer} without checking for updates`);
 			return installedPath;
 		}
-		throw new Error(`${manifest.unreachable}\n  ✖ Failed to fetch manifest.`);
+		if (rejectedVer) throw new Error(`${trusted.unreachable}\n  ✖ Installed engine v${rejectedVer} failed verification and cannot be reinstalled offline.\n  Run "${updateCommand}" once the download server is reachable.`);
+		throw new Error(`${trusted.unreachable}\n  ✖ Failed to fetch manifest.`);
 	}
+	const { manifest, envelope } = trusted;
 	writeLastCheck(enginesDir, now());
 	const stableVersion = manifest.version;
 	if (!compatible(stableVersion)) {
@@ -331,11 +435,13 @@ async function resolveEngine(options) {
 	}
 	const target = manifest.targets[binaryName];
 	if (!target) throw new Error(`No binary available for ${binaryName}\n  Available: ${Object.keys(manifest.targets).join(", ")}`);
+	if (!/^[0-9a-f]{64}$/.test(target.binary_sha256 ?? "")) throw new Error(`Engine v${stableVersion} has no signed binary hash for ${binaryName}; it cannot be verified after install.`);
 	if (installedPath && installedVer && !force && compareVersions(stableVersion, installedVer) <= 0) {
 		log(`  ✓ Engine v${installedVer} is up to date (stable: v${stableVersion})`);
 		return installedPath;
 	}
-	if (!installedVer) log(`  Engine not found. Downloading v${stableVersion}...`);
+	if (rejectedVer) log(`  Reinstalling engine v${stableVersion}...`);
+	else if (!installedVer) log(`  Engine not found. Downloading v${stableVersion}...`);
 	else if (compareVersions(stableVersion, installedVer) > 0) log(`  Update available: v${installedVer} → v${stableVersion}`);
 	else log(`  Reinstalling engine v${stableVersion}...`);
 	log(`  Requesting download URL...`);
@@ -350,6 +456,8 @@ async function resolveEngine(options) {
 		version: stableVersion,
 		binaryName,
 		expectedSha256: target.sha256,
+		expectedBinarySha256: target.binary_sha256,
+		envelope,
 		log
 	});
 }
@@ -358,8 +466,9 @@ async function checkForUpdate(options) {
 	const { enginesDir, binaryName, cliVersion, now = Date.now } = options;
 	const compatible = (version) => isCompatibleEngine(cliVersion, version);
 	const installed = detectInstalledVersion(enginesDir, binaryName, compatible);
-	const manifest = await fetchTrustedManifest(options);
-	if ("unreachable" in manifest) throw new Error(manifest.unreachable);
+	const trusted = await fetchTrustedManifest(options);
+	if ("unreachable" in trusted) throw new Error(trusted.unreachable);
+	const { manifest } = trusted;
 	writeLastCheck(enginesDir, now());
 	const latestCompatible = compatible(manifest.version);
 	return {
@@ -488,6 +597,11 @@ async function main() {
 		console.log("  JSORM_NO_UPDATE_CHECK=1   Skip engine update checks while an engine is installed");
 		return;
 	}
+	try {
+		ensureOwnerOnlyDir(dirname(ENGINES_DIR));
+	} catch (err) {
+		console.error(`  ⚠ Could not restrict ${dirname(ENGINES_DIR)}: ${err instanceof Error ? err.message : err}`);
+	}
 	const resolveOptions = {
 		enginesDir: ENGINES_DIR,
 		binaryName: getEngineBinaryName(),
@@ -495,6 +609,7 @@ async function main() {
 		downloadUrl: STABLE_DOWNLOAD_URL,
 		cliVersion: readVersion(),
 		skipUpdateCheck: process.env.JSORM_NO_UPDATE_CHECK === "1",
+		updateCommand: `${cliRunner(detectPackageManager())} update`,
 		log: console.log
 	};
 	try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jsorm/cli",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI de JSORM",
   "license": "MPL-2.0",
   "repository": {
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@jsorm/core": "1.2.0"
+    "@jsorm/core": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",