promptkit-os 1.10.0 → 1.11.0

package/README.md

@@ -1,6 +1,8 @@
 # `promptkit-os` (npm)
 
-The **courier**, not the product. PromptKit OS itself is pure markdown with no runtime, no daemon, and no model lock-in — it lives at [lowqualityloey/promptkit-os](https://github.com/lowqualityloey/promptkit-os).
+The open-source engineering control plane for AI coding agents (Claude Code, Cursor, Copilot, Antigravity, Gemini CLI) — managing task ceremony levels (L0–L3), context economy, JIT stack playbooks, and evidence-gated verification.
+
+> **Note**: This npm package is the **courier**, not the product. PromptKit OS itself is pure repository-native markdown with no runtime, no daemon, and no model lock-in — it lives at [lowqualityloey/promptkit-os](https://github.com/lowqualityloey/promptkit-os).
 
 This package does one thing: fetch the GitHub release tarball that matches its own version, extract it into `./.promptkit/`, and run the canonical `init.sh` (POSIX) or `init.ps1` (Windows). All installation logic stays in the fetched repository; nothing is reimplemented here.
 

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,32 @@ 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.
+//
+// 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).
+//
+// 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",
+};
+
 function die(msg) {
   process.stderr.write(`[promptkit-os] ${msg}\n`);
   process.exit(1);
@@ -78,6 +105,30 @@ function projectRootFrom(args) {
   return path.resolve(positional[0] || process.cwd());
 }
 
+function expectedTarballDigest(version) {
+  const override = process.env.PROMPTKIT_TARBALL_SHA256;
+  if (override !== undefined && override !== "") return override;
+  return TARBALL_SHA256_BY_VERSION[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().
+function verifyTarballIntegrity(tarball, expectedHex, version) {
+  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} ` +
+        `(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" });
@@ -150,10 +201,29 @@ async function main() {
   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"
+    );
+  }
   await extract(tarball, kitDir);
   process.stderr.write(`[promptkit-os] extracted release v${version} into ${KIT_DIR}/\n`);
 
   runInstaller(kitDir, args);
 }
 
-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 };
+}

package/package.json

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