nestweaver 9.0.5 → 9.1.0

package/README.md

@@ -8,11 +8,25 @@ binary matching this package's version from the project's GitHub Releases,
 verifies it against the SHA-256 published alongside the archive, and puts a
 `nestweaver` executable on your PATH.
 
+**Lifecycle scripts must be enabled.** The binary is fetched in `postinstall`,
+so `npm install --ignore-scripts` — and **pnpm 10+, which blocks lifecycle
+scripts by default** — leave you with a wrapper and no binary. `nestweaver` then
+exits 1 saying the binary was not found. With pnpm, allow it explicitly:
+
+```jsonc
+// package.json
+{ "pnpm": { "onlyBuiltDependencies": ["nestweaver"] } }
+```
+
+If your organisation disallows install scripts outright, install a release
+archive from GitHub or build from source (`cargo install --locked --path .`)
+instead.
+
 ## Platforms
 
 macOS and Linux, on x86_64 and arm64. On any other platform the install step
-exits without failing and prints the supported targets; use a release archive
-or a source build instead.
+FAILS and prints the supported targets, rather than leaving you with a wrapper
+that cannot run; use a release archive or a source build instead.
 
 Linux builds target **glibc 2.35**, which covers Ubuntu 22.04 LTS and newer and
 Debian 12. The archive includes the GCC 13 runtime LadybugDB needs and the npm

package/install.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+"use strict";
 
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 
@@ -11,72 +12,357 @@ const PLATFORM_MAP = {
   "linux-arm64": "aarch64-unknown-linux-gnu",
 };
 
-const key = `${process.platform}-${process.arch}`;
-const target = PLATFORM_MAP[key];
+const repo = "Kehl-io/nestweaver";
+
+// ── Decision logic ──────────────────────────────────────────────────────
+// Pure, exported, and covered by install.test.js. Everything below the
+// `main()` boundary does I/O and is not directly testable; keeping the
+// judgements out here is what makes the installer assertable at all.
 
-if (!target) {
-  console.warn(`Unsupported platform: ${key}`);
-  console.warn("Supported: darwin-x64, darwin-arm64, linux-x64, linux-arm64");
-  console.warn(
-    "Unsupported platform. Install a verified GitHub Release archive for a supported target, or from a source checkout: cargo install --locked --path .",
+/// Explicit boolean parsing for operator-facing env vars. `0`, `false`, `no`,
+/// `off` and blank all mean OFF; anything else non-blank means ON.
+function isTruthyEnv(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return !["0", "false", "no", "off"].includes(normalized);
+}
+
+/// Whether a GitHub Release may be trusted to anchor its own checksum.
+///
+/// The checksum lives beside the archive in the same release, so an actor who
+/// can replace release assets can replace both. Only an IMMUTABLE release makes
+/// the checksum tamper-evidence rather than a self-signed claim.
+///
+/// A wrong tag is always fatal. A non-immutable release is DISCLOSED, not
+/// refused: immutable releases were enabled on this repository only recently,
+/// so every version already on the npm registry reports `immutable: false`
+/// (verified against the live API for v9.0.0, v9.0.4 and v9.0.5). Refusing them
+/// would make `npm install nestweaver` fail for every published version --
+/// a self-inflicted outage, not a security control. The checksum is still
+/// fetched and still enforced; what is absent is tamper-evidence, and saying so
+/// is the honest form. `NESTWEAVER_REQUIRE_IMMUTABLE_RELEASE=1` opts into the
+/// strict contract for callers who want it.
+function assessReleaseTrust(release, tag, env) {
+  const actualTag = release && release.tag_name;
+  if (actualTag !== tag) {
+    return {
+      failure: `GitHub Release tag ${JSON.stringify(actualTag)} does not match the requested ${tag}`,
+      warning: null,
+    };
+  }
+  if (release.immutable === true) {
+    return { failure: null, warning: null };
+  }
+  // Any non-blank value used to mean "strict", so an operator writing
+  // NESTWEAVER_REQUIRE_IMMUTABLE_RELEASE=0 to opt OUT was opted IN and every
+  // build failed.
+  const strict = isTruthyEnv(env && env.NESTWEAVER_REQUIRE_IMMUTABLE_RELEASE);
+  const detail =
+    `GitHub Release ${tag} is not immutable, so its published SHA-256 could have been ` +
+    `replaced together with its archive. The checksum is still verified, but it is not ` +
+    `tamper-evidence. Releases published before immutable releases were enabled on this ` +
+    `repository all report this.`;
+  if (strict) {
+    return {
+      failure: `${detail} NESTWEAVER_REQUIRE_IMMUTABLE_RELEASE is set, so this install is refused.`,
+      warning: null,
+    };
+  }
+  return {
+    failure: null,
+    warning: `${detail} Set NESTWEAVER_REQUIRE_IMMUTABLE_RELEASE=1 to refuse instead of warn.`,
+  };
+}
+
+/// Whether the binary that was just installed IS the version this package
+/// claims. Executing `--version` only proves the file runs; comparing its
+/// output is what proves identity, and the previous implementation piped that
+/// output straight to the terminal and compared nothing.
+function runtimeVersionFailure(versionOutput, expected) {
+  // First line only, and the version must be reported AS the version -- i.e.
+  // `<name> <version>`. Accepting the token anywhere in the output let prose
+  // such as "9.0.6 is not this build; actual 1.0.0" pass.
+  const firstLine = String(versionOutput || "").trim().split(/\r?\n/)[0] || "";
+  const tokens = firstLine.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return `the installed binary printed no version output; expected ${expected}`;
+  }
+  // The version must sit where a version goes: `<name> <version>` (the shape
+  // `nestweaver --version` actually prints), or a bare version on its own.
+  // Exact token match, so 9.0.60 can never satisfy a request for 9.0.6.
+  const reported = tokens.length === 1 ? tokens[0] : tokens[1];
+  if (reported === expected) {
+    return null;
+  }
+  return `the installed binary reports ${JSON.stringify(
+    String(versionOutput).trim(),
+  )}, which does not contain the expected version ${expected}`;
+}
+
+/// Headers for the release-metadata call.
+///
+/// Unauthenticated api.github.com allows 60 requests/hour/IP, so a shared CI
+/// egress or a corporate NAT exhausts it and every install behind that address
+/// fails. A token raises the ceiling to 5,000 and is already present in
+/// virtually every CI environment.
+///
+/// TWO SEPARATE PROPERTIES, and only one of them is about the URL. The URL is a
+/// fixed api.github.com constant, so the credential cannot be sent anywhere
+/// else. But the credential must also not be EXPOSED where it is sent from:
+/// passing it as a curl argv element publishes it to every local user through
+/// the process table (`/proc/<pid>/cmdline` is world-readable on Linux, which
+/// is what CI runners are), so `fetchRelease` feeds these to curl on stdin via
+/// `--config -` rather than as `-H` arguments.
+function githubApiHeaders(env) {
+  const headers = [
+    "Accept: application/vnd.github+json",
+    "X-GitHub-Api-Version: 2026-03-10",
+  ];
+  const token = [env && env.GITHUB_TOKEN, env && env.GH_TOKEN]
+    .map((value) => String(value || "").trim())
+    .find((value) => value.length > 0);
+  if (token) {
+    headers.push(`Authorization: Bearer ${token}`);
+  }
+  return headers;
+}
+
+/// Turn a failed release-metadata call into something the caller can act on.
+/// Failing closed is correct; failing closed without naming the remedy is what
+/// makes a rate limit look like a broken package.
+function describeReleaseApiFailure(failure, env) {
+  const status = failure && failure.status;
+  const body = String((failure && failure.body) || "").trim();
+  const authenticated = githubApiHeaders(env).some((header) =>
+    header.startsWith("Authorization"),
   );
-  process.exit(0); // Don't break npm install
+  if (status === 401) {
+    return authenticated
+      ? `GitHub rejected the credential in GITHUB_TOKEN/GH_TOKEN (HTTP 401: ${body}). This endpoint needs no credential for a public repository -- unset that variable, or replace the expired or wrong-scope token.`
+      : `GitHub returned HTTP 401 for an unauthenticated request: ${body}`;
+  }
+  if ((status === 403 || status === 429) && /rate limit/i.test(body)) {
+    return authenticated
+      ? `the GitHub API rate limit was exhausted for the credential in use; wait for the limit to reset and retry: ${body}`
+      : `the GitHub API rate limit was exhausted for this IP address (unauthenticated callers get 60 requests/hour, and a shared CI or NAT egress exhausts that quickly). Export GITHUB_TOKEN or GH_TOKEN to raise it, or wait for the limit to reset: ${body}`;
+  }
+  if (status === 404) {
+    return `the GitHub Release was not found (HTTP 404); the tag may not be published yet: ${body}`;
+  }
+  return `could not read GitHub Release metadata${status ? ` (HTTP ${status})` : ""}: ${body}`;
 }
 
-const version = require("./package.json").version;
-const repo = "Kehl-io/nestweaver";
-// Release tags are `v<version>` (release-please config: include-component-in-tag
-// false) and assets are `nestweaver-v<version>-<target>.tar.gz` (see the
-// `build` job in .github/workflows/release-please.yml). Keep these in sync.
-const tag = `v${version}`;
-const archive = `nestweaver-${tag}-${target}.tar.gz`;
-const base = `https://github.com/${repo}/releases/download/${tag}`;
-const url = `${base}/${archive}`;
+module.exports = {
+  assessReleaseTrust,
+  runtimeVersionFailure,
+  githubApiHeaders,
+  describeReleaseApiFailure,
+};
+
+// ── Installation ────────────────────────────────────────────────────────
+
+/// One release-metadata request. Returns `{ status, body }`; never throws for
+/// an HTTP error, so the caller can decide whether to retry.
+///
+/// `--fail-with-body`, NOT `-f`. Plain `-f` suppresses the response body on an
+/// HTTP error, which left `describeReleaseApiFailure` matching /rate limit/
+/// against a body that could only ever be the three-digit status -- so the
+/// rate-limit branch, the entire reason the token handling exists, was
+/// unreachable. Verified: with `-f` the recovered body is the literal "404".
+///
+/// Headers go over stdin via `--config -` so a bearer token never appears in
+/// this process's argv.
+function requestRelease(url, headers) {
+  // The URL stays a normal argument: it is not a secret, and keeping it in
+  // argv is what lets tooling (and the release gate's fake curl) see which
+  // request is being made. ONLY the headers go over stdin, because that is
+  // where the bearer token lives.
+  const args = [
+    "--fail-with-body",
+    "-sSL",
+    "--write-out",
+    "\n%{http_code}",
+    "--config",
+    "-",
+    url,
+  ];
+  const config = headers
+    .map((header) => `header = ${JSON.stringify(header)}`)
+    .join("\n");
+  let raw;
+  try {
+    raw = execFileSync("curl", args, {
+      input: config,
+      maxBuffer: 32 * 1024 * 1024,
+    }).toString();
+  } catch (error) {
+    const stdout = String((error && error.stdout) || "");
+    if (stdout.length === 0) {
+      // curl never ran, or died before writing: ENOENT / timeout / DNS.
+      // `error.message` is safe to surface here because these arms carry no
+      // argv -- and argv no longer carries the token in any case.
+      return { status: 0, body: String((error && error.message) || error) };
+    }
+    raw = stdout;
+  }
+  const lines = raw.split("\n");
+  const status = Number(lines.pop().trim()) || 0;
+  return { status, body: lines.join("\n").trim() };
+}
 
-const binDir = path.join(__dirname, ".nestweaver-bin");
-fs.mkdirSync(binDir, { recursive: true });
-const archivePath = path.join(binDir, archive);
+function fetchRelease(url, env) {
+  const headers = githubApiHeaders(env);
+  const authenticated = headers.some((header) => header.startsWith("Authorization"));
+  let result = requestRelease(url, headers);
 
-console.log(`Downloading NestWeaver v${version} for ${target}...`);
+  // This endpoint needs no credential for a public repository, so an ambient
+  // GITHUB_TOKEN/GH_TOKEN can only ever make it worse: `gh auth login` and
+  // composite workflows routinely export a stale or wrong-scope token, which
+  // turns a request that would have succeeded anonymously into a hard 401.
+  // Retry once without it rather than failing on a credential the caller never
+  // asked us to use. Rate-limited responses are NOT retried -- dropping the
+  // token there would make the limit stricter, not looser.
+  if (
+    authenticated &&
+    (result.status === 401 || (result.status === 403 && !/rate limit/i.test(result.body)))
+  ) {
+    const anonymous = headers.filter((header) => !header.startsWith("Authorization"));
+    const retry = requestRelease(url, anonymous);
+    if (retry.status === 200) {
+      result = retry;
+    }
+  }
+
+  if (result.status !== 200) {
+    throw new Error(describeReleaseApiFailure(result, env));
+  }
+  try {
+    return JSON.parse(result.body);
+  } catch (error) {
+    throw new Error(`GitHub Release metadata was not valid JSON: ${error.message}`);
+  }
+}
+
+function main() {
+  const key = `${process.platform}-${process.arch}`;
+  const target = PLATFORM_MAP[key];
+  const binDir = path.join(__dirname, ".nestweaver-bin");
+  const binaryPath = path.join(binDir, "nestweaver");
+  fs.mkdirSync(binDir, { recursive: true });
+  // Never let a failed upgrade leave the newly installed wrapper executing a
+  // binary from an older package version, or a previous run's disclosure
+  // describing a release this run did not install.
+  fs.rmSync(binaryPath, { force: true });
+  fs.rmSync(path.join(binDir, "RELEASE-NOT-IMMUTABLE.txt"), { force: true });
+
+  if (!target) {
+    console.error(`Unsupported platform: ${key}`);
+    console.error("Supported: darwin-x64, darwin-arm64, linux-x64, linux-arm64");
+    console.error(
+      "Unsupported platform. Install a verified GitHub Release archive for a supported target, or from a source checkout: cargo install --locked --path .",
+    );
+    process.exit(1);
+  }
 
-try {
-  execSync(`curl -fsSL "${url}" -o "${archivePath}"`, { stdio: "inherit" });
+  const version = require("./package.json").version;
+  // Release tags are `v<version>` (release-please config: include-component-in-tag
+  // false) and assets are `nestweaver-v<version>-<target>.tar.gz` (see the
+  // `build` job in .github/workflows/release-please.yml). Keep these in sync.
+  const tag = `v${version}`;
+  const archive = `nestweaver-${tag}-${target}.tar.gz`;
+  const base = `https://github.com/${repo}/releases/download/${tag}`;
+  const url = `${base}/${archive}`;
+  const releaseApiUrl = `https://api.github.com/repos/${repo}/releases/tags/${tag}`;
+  const archivePath = path.join(binDir, archive);
+
+  console.log(`Downloading NestWeaver v${version} for ${target}...`);
 
-  // Verify the SHA-256 the release ships alongside the archive — a mismatch
-  // means a corrupted or tampered download, which must fail loudly.
   try {
-    const expected = execSync(`curl -fsSL "${url}.sha256"`)
+    const trust = assessReleaseTrust(
+      fetchRelease(releaseApiUrl, process.env),
+      tag,
+      process.env,
+    );
+    if (trust.failure) {
+      throw new Error(trust.failure);
+    }
+    if (trust.warning) {
+      // npm >= 7 HIDES lifecycle-script output unless the script fails or
+      // --foreground-scripts is passed, so a console warning alone does not
+      // reach an ordinary `npm install` user -- which would make "disclosed"
+      // a claim this code does not deliver. Leave it on disk beside the binary
+      // as well, so the disclosure is greppable after the fact.
+      console.warn(`Warning: ${trust.warning}`);
+      try {
+        fs.writeFileSync(
+          path.join(binDir, "RELEASE-NOT-IMMUTABLE.txt"),
+          `${trust.warning}\n\nRelease: ${tag}\nArchive: ${url}\n`,
+        );
+      } catch {
+        // Best effort: a disclosure that cannot be written must not fail an
+        // install whose checksum verified.
+      }
+    }
+
+    execFileSync("curl", ["-fsSL", url, "-o", archivePath], { stdio: "inherit" });
+
+    // Verify the SHA-256 the release ships alongside the archive — a mismatch
+    // means a corrupted or tampered download. Missing, unreadable, or malformed
+    // checksum evidence is equally non-authoritative and must fail closed.
+    const expected = execFileSync("curl", ["-fsSL", `${url}.sha256`])
       .toString()
       .trim()
       .split(/\s+/)[0];
-    const actual = execSync(`shasum -a 256 "${archivePath}"`)
+    const actual = execFileSync("shasum", ["-a", "256", archivePath])
       .toString()
       .trim()
       .split(/\s+/)[0];
-    if (expected && actual && expected !== actual) {
-      throw new Error(
-        `checksum mismatch: expected ${expected}, got ${actual}`,
-      );
+    if (!/^[0-9a-f]{64}$/i.test(expected) || !/^[0-9a-f]{64}$/i.test(actual)) {
+      throw new Error("release checksum evidence is missing or malformed");
+    }
+    if (expected.toLowerCase() !== actual.toLowerCase()) {
+      throw new Error(`checksum mismatch: expected ${expected}, got ${actual}`);
     }
-  } catch (checksumErr) {
-    if (String(checksumErr.message || "").includes("checksum mismatch")) {
-      throw checksumErr; // integrity failure — do not install
+
+    execFileSync("tar", ["xz", "-C", binDir, "-f", archivePath], {
+      stdio: "inherit",
+    });
+    if (!fs.existsSync(binaryPath) || !fs.statSync(binaryPath).isFile()) {
+      throw new Error("verified archive did not contain the nestweaver executable");
+    }
+    fs.rmSync(archivePath, { force: true });
+    fs.chmodSync(binaryPath, 0o755);
+
+    // Capture, do not inherit: piping `--version` to the terminal proves the
+    // binary executes and compares nothing.
+    const reported = execFileSync(binaryPath, ["--version"]).toString();
+    const versionFailure = runtimeVersionFailure(reported, version);
+    if (versionFailure) {
+      throw new Error(versionFailure);
     }
-    // Missing/unreadable .sha256 is not fatal; proceed with the download.
+    console.log(`NestWeaver installed successfully (${reported.trim()}).`);
+    console.log(
+      "Upgrading an existing pre-publication brain? Stop its daemon and run `nestweaver publication rebuild --config /path/to/instance.toml`; the incumbent remains recoverable until validated cutover.",
+    );
+  } catch (err) {
+    fs.rmSync(archivePath, { force: true });
+    // Extraction and the runtime identity check happen after checksum
+    // validation. A failure there must not leave a candidate binary that npm
+    // would expose.
+    fs.rmSync(binaryPath, { force: true });
+    console.error(`Failed to install NestWeaver binary: ${err.message}`);
+    console.error(`  URL: ${url}`);
+    console.error(
+      "Download a verified GitHub Release archive, or build from a source checkout: cargo install --locked --path .",
+    );
+    process.exit(1);
   }
+}
 
-  execSync(`tar xz -C "${binDir}" -f "${archivePath}"`, { stdio: "inherit" });
-  fs.rmSync(archivePath, { force: true });
-  fs.chmodSync(path.join(binDir, "nestweaver"), 0o755);
-  console.log("NestWeaver installed successfully.");
-  console.log(
-    "Upgrading an existing pre-publication brain? Stop its daemon and run `nestweaver publication rebuild --config /path/to/instance.toml`; the incumbent remains recoverable until validated cutover.",
-  );
-} catch (err) {
-  console.warn(`Failed to install NestWeaver binary: ${err.message}`);
-  console.warn(`  URL: ${url}`);
-  console.warn(
-    "Download a verified GitHub Release archive, or build from a source checkout: cargo install --locked --path .",
-  );
-  process.exit(0); // Don't break npm install on transient/network failures
+// Only install when executed as the postinstall script; `require` must be free
+// of side effects so the decision logic above can be tested at all.
+if (require.main === module) {
+  main();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestweaver",
-  "version": "9.0.5",
+  "version": "9.1.0",
   "description": "Code knowledge graph for AI agents — 42 MCP tools, 32 languages, graph visualization",
   "bin": {
     "nestweaver": "bin/nestweaver"
@@ -21,6 +21,9 @@
     "x64",
     "arm64"
   ],
+  "libc": [
+    "glibc"
+  ],
   "keywords": [
     "mcp",
     "code-graph",