promptkit-os 1.10.1 → 2.0.0

package/README.md

@@ -28,7 +28,7 @@ If `.promptkit/` already exists and is not empty, the courier **refuses to overl
 # git-submodule install
 git submodule update --remote --merge .promptkit && bash .promptkit/init.sh
 
-# courier install (tarball is pinned per version — replace it)
+# courier install (replace the existing tree; new couriers verify the archive)
 rm -rf .promptkit
 npx promptkit-os@latest --balanced
 ```
@@ -37,7 +37,11 @@ The courier detects which case applies (a submodule install has `.promptkit/.git
 
 ## Version pinning
 
-`npx promptkit-os@X.Y.Z` fetches release tag `vX.Y.Z` and never a moving ref, so a given install is reproducible forever.
+`npx promptkit-os@X.Y.Z` fetches the GitHub archive for tag `vX.Y.Z`, not a branch head. New couriers require a valid SHA-256 digest for their own version before download and verify the archive **before** creating `.promptkit/`, extracting files, or running the installer. The release workflow independently checks the tagged archive, injects the digest, and checks the actual npm-packed courier before publication. A missing or mismatched digest stops installation; it is not a warning-only path.
+
+**Historical exception:** the already-published immutable npm courier `promptkit-os@1.11.0` did not contain its own archive pin and warns/proceeds by default. npm package integrity/provenance authenticates that npm tarball, **not** the second-stage GitHub archive it downloads. Existing installed files are not retroactively checked or changed by the new policy. For `1.11.0`, an operator can independently obtain a trusted archive SHA-256 and set both `PROMPTKIT_TARBALL_SHA256=<trusted-64-hex-sha256>` and `PROMPTKIT_REQUIRE_INTEGRITY_PIN=1` (in PowerShell, set `$env:PROMPTKIT_TARBALL_SHA256` and `$env:PROMPTKIT_REQUIRE_INTEGRITY_PIN`); the published courier verifies the override before extraction. New couriers also accept an explicitly supplied trusted `PROMPTKIT_TARBALL_SHA256` for archive rotation. The override is an **operator-controlled trust input**: do not derive it from the same untrusted download, and investigate a mismatch rather than disabling verification.
+
+GitHub-generated tag archives are not guaranteed byte-for-byte immutable forever. A legitimate archive-regeneration change may require a separately verified override or a new courier release; a fixed tag name alone does not guarantee reproducible archive bytes.
 
 ## Removal
 

package/bin/promptkit-os.js

@@ -9,6 +9,7 @@
 "use strict";
 
 const { spawnSync } = require("node:child_process");
+const crypto = require("node:crypto");
 const fs = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
@@ -17,6 +18,31 @@ const PKG = require("../package.json");
 const REPO = "lowqualityloey/promptkit-os";
 const KIT_DIR = ".promptkit";
 
+// Pinned SHA-256 (hex) of the GitHub release tarball per courier version.
+// This lives here — not in a sidecar file — because release-npm.yml enforces an
+// npm-pack allowlist of exactly { package.json, README.md, bin/promptkit-os.js };
+// a sidecar would either be excluded from the published package (useless) or
+// require a workflow change to allowlist.
+//
+// Release pins are inserted and checked by the repository release workflow after
+// it checks out the tag and before npm publication. Do not mint pins by hand. A
+// missing or invalid own-version pin fails closed before download. An explicitly
+// supplied PROMPTKIT_TARBALL_SHA256 overrides the map as an operator-controlled
+// trust input for testing or archive rotation.
+//
+// CAVEAT: these digests pin GitHub's *generated* archive for a tag. That archive
+// is reproducible today (verified by double download when each pin was minted)
+// but is not contractually immutable — a future GitHub-side change to archive
+// generation would change the bytes and make this pin reject an untampered
+// download. On mismatch, confirm the release tag and the release evidence
+// record before treating it as tampering; rotate with PROMPTKIT_TARBALL_SHA256.
+const TARBALL_SHA256_BY_VERSION = {
+  "1.10.1": "1e55459914a1c46aa71df8f9cb8ce4c9ff37d1c02d67f70e5607b3bfd4f48d4b",
+  "1.11.0": "6503fdfcde286055b8c053aa0ffa8bdf244cf77df3321cccd6a8d8f780195ade",
+  "2.0.0": "4fb5b9d85e0f19bfe333c361e00465705b60636a8026edd62c15c6f2d61cbf4b",
+  // @pin-insert
+};
+
 function die(msg) {
   process.stderr.write(`[promptkit-os] ${msg}\n`);
   process.exit(1);
@@ -78,6 +104,38 @@ function projectRootFrom(args) {
   return path.resolve(positional[0] || process.cwd());
 }
 
+function normalizedDigest(digest, version) {
+  if (typeof digest !== "string" || !/^[0-9a-fA-F]{64}$/.test(digest)) {
+    die(`invalid SHA-256 digest for v${version} — expected exactly 64 hexadecimal characters; refusing to download, extract or execute`);
+  }
+  return digest.toLowerCase();
+}
+
+function expectedTarballDigest(version) {
+  const override = process.env.PROMPTKIT_TARBALL_SHA256;
+  const digest = override === undefined ? TARBALL_SHA256_BY_VERSION[version] : override;
+  if (digest === undefined) {
+    die(`no integrity pin for v${version} — refusing to download, extract or execute; supply a trusted PROMPTKIT_TARBALL_SHA256`);
+  }
+  return normalizedDigest(digest, version);
+}
+
+// Aborts (non-zero exit, no extract, no exec) unless `tarball` hashes to
+// `expectedHex`. Comparison is constant-time. Must be called after download()
+// and before extract().
+function verifyTarballIntegrity(tarball, expectedHex, version) {
+  const expected = Buffer.from(normalizedDigest(expectedHex, version), "hex");
+  const actual = crypto.createHash("sha256").update(tarball).digest();
+  if (expected.length !== actual.length || !crypto.timingSafeEqual(actual, expected)) {
+    die(
+      `tarball integrity mismatch for v${version} ` +
+        `(expected sha256 ${expectedHex}, got ${actual.toString("hex")}): ` +
+        "refusing to extract or execute — the download may have been tampered with. " +
+        "If this version was just released, the pin in TARBALL_SHA256_BY_VERSION needs updating (see above)."
+    );
+  }
+}
+
 async function download(url) {
   process.stderr.write(`[promptkit-os] fetching ${url}\n`);
   const res = await fetch(url, { redirect: "follow" });
@@ -111,6 +169,10 @@ function runInstaller(kitDir, args) {
   }
 }
 
+function installerArgs(args, version) {
+  return [...args, `--engine-version=v${version}`];
+}
+
 async function main() {
   const version = PKG.version;
   if (version === "0.0.0") {
@@ -147,13 +209,20 @@ async function main() {
   const url = `https://github.com/${REPO}/archive/refs/tags/v${version}.tar.gz`;
   const kitDir = path.join(root, KIT_DIR);
   assertInstallTargetIsClean(kitDir, force);
-  fs.mkdirSync(kitDir, { recursive: true });
 
+  const expectedDigest = expectedTarballDigest(version);
   const tarball = await download(url);
+  verifyTarballIntegrity(tarball, expectedDigest, version);
+  process.stderr.write(`[promptkit-os] verified release tarball integrity (sha256) for v${version}\n`);
+  fs.mkdirSync(kitDir, { recursive: true });
   await extract(tarball, kitDir);
   process.stderr.write(`[promptkit-os] extracted release v${version} into ${KIT_DIR}/\n`);
 
-  runInstaller(kitDir, args);
+  runInstaller(kitDir, installerArgs(args, version));
 }
 
-main().catch((err) => die(err && err.message ? err.message : String(err)));
+if (require.main === module) {
+  main().catch((err) => die(err && err.message ? err.message : String(err)));
+} else {
+  module.exports = { verifyTarballIntegrity, expectedTarballDigest, TARBALL_SHA256_BY_VERSION, installerArgs };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptkit-os",
-  "version": "1.10.1",
+  "version": "2.0.0",
   "description": "Courier for PromptKit OS: fetches a pinned release tarball and runs the canonical installer. Not a runtime dependency.",
   "keywords": [
     "promptkit",