promptkit-os 1.11.0 → 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

@@ -24,15 +24,11 @@ const KIT_DIR = ".promptkit";
 // a sidecar would either be excluded from the published package (useless) or
 // require a workflow change to allowlist.
 //
-// UPDATE INSTRUCTION FOR RELEASES: after pushing tag vX.Y.Z (and before the npm
-// publish), download the immutable release tarball, hash it, and add the entry:
-//   curl -sL "https://github.com/lowqualityloey/promptkit-os/archive/refs/tags/vX.Y.Z.tar.gz" -o /tmp/release.tar.gz
-//   sha256sum /tmp/release.tar.gz
-// then add `"X.Y.Z": "<64-hex-chars>",` below so the courier verifies that exact
-// tarball before extracting or executing anything from it. If no pin exists for
-// the running version the courier warns loudly and continues (pins can only be
-// minted after the tag exists); set PROMPTKIT_REQUIRE_INTEGRITY_PIN=1 to fail
-// closed instead. PROMPTKIT_TARBALL_SHA256 overrides the map (testing / rotation).
+// 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)
@@ -42,6 +38,9 @@ const KIT_DIR = ".promptkit";
 // 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) {
@@ -105,20 +104,28 @@ 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;
-  if (override !== undefined && override !== "") return override;
-  return TARBALL_SHA256_BY_VERSION[version];
+  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 so a MITM learns nothing about the
-// pin from timing. Must be called after download() and before extract().
+// `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();
-  const expected = Buffer.from(String(expectedHex), "hex");
-  // Buffer.from(hex) never throws on bad input — it truncates — so the length
-  // check below is what turns a malformed pin into a mismatch (fail closed).
   if (expected.length !== actual.length || !crypto.timingSafeEqual(actual, expected)) {
     die(
       `tarball integrity mismatch for v${version} ` +
@@ -162,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") {
@@ -198,32 +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 tarball = await download(url);
   const expectedDigest = expectedTarballDigest(version);
-  if (expectedDigest) {
-    verifyTarballIntegrity(tarball, expectedDigest, version);
-    process.stderr.write(`[promptkit-os] verified release tarball integrity (sha256) for v${version}\n`);
-  } else if (process.env.PROMPTKIT_REQUIRE_INTEGRITY_PIN === "1") {
-    die(
-      `no integrity pin for v${version} — refusing to extract or execute. ` +
-        "Add the sha256 of the release tarball to TARBALL_SHA256_BY_VERSION (see above)."
-    );
-  } else {
-    process.stderr.write(
-      `[promptkit-os] warning: no integrity pin for v${version}; ` +
-        "proceeding unverified — set PROMPTKIT_REQUIRE_INTEGRITY_PIN=1 to fail closed.\n"
-    );
-  }
+  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));
 }
 
 if (require.main === module) {
   main().catch((err) => die(err && err.message ? err.message : String(err)));
 } else {
-  module.exports = { verifyTarballIntegrity, expectedTarballDigest, TARBALL_SHA256_BY_VERSION };
+  module.exports = { verifyTarballIntegrity, expectedTarballDigest, TARBALL_SHA256_BY_VERSION, installerArgs };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptkit-os",
-  "version": "1.11.0",
+  "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",