@nano-step/nano-brain 2026.6.207 → 2026.6.209

package/README.md

@@ -84,6 +84,33 @@ curl -X POST http://localhost:3100/api/v1/query \
   -d '{"workspace":"<hash>","query":"database decision"}'
 ```
 
+## Verifying Downloads
+
+Every release ships a `SHA256SUMS` asset alongside the four platform binaries.
+You can verify a downloaded binary against the published checksums using
+standard tooling:
+
+```bash
+TAG=v2026.6.2.1   # any release tag
+curl -fLO https://github.com/nano-step/nano-brain/releases/download/$TAG/SHA256SUMS
+curl -fLO https://github.com/nano-step/nano-brain/releases/download/$TAG/nano-brain-linux-amd64
+sha256sum -c SHA256SUMS --ignore-missing
+# nano-brain-linux-amd64: OK
+```
+
+`npm install @nano-step/nano-brain` (and the unscoped `nano-brain` alias)
+performs this verification **automatically** during postinstall — a SHA-256
+mismatch aborts the install with exit code 1 and removes the partial binary.
+
+For air-gapped installs or environments where a corporate proxy modifies the
+download stream, set `NANO_BRAIN_SKIP_SHA_VERIFY=1` before running `npm install`
+to bypass the check (a warning is printed so the bypass is visible in CI logs).
+
+Releases tagged before this feature shipped do not have a `SHA256SUMS` asset;
+installs of those versions succeed with a single WARN line and no verification.
+See issue [#320](https://github.com/nano-step/nano-brain/issues/320) for the
+threat model and rationale.
+
 ## Configuration
 
 Config file: `~/.nano-brain/config.yml`

package/npm/postinstall.js

@@ -5,6 +5,7 @@ const https = require("https");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const crypto = require("crypto");
 const { execSync } = require("child_process");
 
 const VERSION = require("../package.json").version;
@@ -55,6 +56,82 @@ function download(url, dest) {
   });
 }
 
+function downloadWithHash(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    const hash = crypto.createHash("sha256");
+    https.get(url, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        file.close();
+        fs.unlinkSync(dest);
+        return downloadWithHash(res.headers.location, dest).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(dest);
+        return reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+      }
+      res.on("data", (chunk) => hash.update(chunk));
+      res.pipe(file);
+      file.on("finish", () => {
+        file.close(() => resolve(hash.digest("hex")));
+      });
+      res.on("error", (err) => {
+        file.close();
+        if (fs.existsSync(dest)) fs.unlinkSync(dest);
+        reject(err);
+      });
+    }).on("error", (err) => {
+      if (fs.existsSync(dest)) fs.unlinkSync(dest);
+      reject(err);
+    });
+  });
+}
+
+function parseSHA256Line(content, targetFilename) {
+  if (typeof content !== "string" || !content) return null;
+  const lines = content.split(/\r?\n/);
+  const re = /^([a-f0-9]{64})\s+(.+?)\s*$/;
+  for (const line of lines) {
+    const m = line.match(re);
+    if (m && m[2] === targetFilename) return m[1];
+  }
+  return null;
+}
+
+async function verifySHA256(tag, assetName, binPath, computedHex) {
+  const sumsUrl = `https://github.com/${REPO}/releases/download/${tag}/SHA256SUMS`;
+  const sumsPath = `${binPath}.SHA256SUMS.tmp`;
+  let sumsContent;
+  try {
+    await download(sumsUrl, sumsPath);
+    sumsContent = fs.readFileSync(sumsPath, "utf8");
+  } catch (err) {
+    console.warn(`⚠ SHA256SUMS not available for ${tag} (${err.message}); skipping integrity verification.`);
+    return;
+  } finally {
+    if (fs.existsSync(sumsPath)) {
+      try { fs.unlinkSync(sumsPath); } catch (_) {}
+    }
+  }
+
+  const expectedHex = parseSHA256Line(sumsContent, assetName);
+  if (!expectedHex) {
+    console.warn(`⚠ ${assetName} not listed in SHA256SUMS for ${tag}; skipping integrity verification.`);
+    return;
+  }
+
+  if (expectedHex.toLowerCase() !== computedHex.toLowerCase()) {
+    if (fs.existsSync(binPath)) fs.unlinkSync(binPath);
+    throw new Error(
+      `SECURITY: SHA-256 mismatch for ${assetName}\n` +
+      `  expected: ${expectedHex}\n` +
+      `  computed: ${computedHex}\n` +
+      `Binary has been deleted. Build from source: CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain`
+    );
+  }
+}
+
 // npm normalizes leading zeros in semver numeric identifiers (e.g. tag
 // v2026.6.0101 publishes as 2026.6.101). Auto-tag uses a fixed-width 4-digit
 // patch {DD}{NN} for new tags, but older history has 1-3 digit patches. Try
@@ -112,6 +189,11 @@ async function main() {
   const binName = os.platform() === "win32" ? "nano-brain.exe" : "nano-brain";
   const binPath = path.join(__dirname, binName);
 
+  const skipVerify = !!process.env.NANO_BRAIN_SKIP_SHA_VERIFY;
+  if (skipVerify) {
+    console.warn("⚠ NANO_BRAIN_SKIP_SHA_VERIFY is set; binary integrity check will be skipped.");
+  }
+
   if (fs.existsSync(binPath)) {
     try {
       const output = execSync(`"${binPath}" version --json`, { timeout: 5000 }).toString();
@@ -131,11 +213,20 @@ async function main() {
   for (const tag of candidateTagsForVersion(VERSION)) {
     const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
     try {
-      await download(url, binPath);
+      if (skipVerify) {
+        await download(url, binPath);
+      } else {
+        const computedHex = await downloadWithHash(url, binPath);
+        await verifySHA256(tag, assetName, binPath, computedHex);
+      }
       fs.chmodSync(binPath, 0o755);
       console.log(`nano-brain v${VERSION} installed successfully from ${tag}.`);
       return;
     } catch (err) {
+      if (err && typeof err.message === "string" && err.message.startsWith("SECURITY:")) {
+        console.error(err.message);
+        process.exit(1);
+      }
       lastErr = err;
     }
   }
@@ -144,12 +235,21 @@ async function main() {
     const tag = await resolveTagFromAPI(VERSION, assetName);
     if (tag) {
       const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
-      await download(url, binPath);
+      if (skipVerify) {
+        await download(url, binPath);
+      } else {
+        const computedHex = await downloadWithHash(url, binPath);
+        await verifySHA256(tag, assetName, binPath, computedHex);
+      }
       fs.chmodSync(binPath, 0o755);
       console.log(`nano-brain v${VERSION} installed successfully from ${tag} (API fallback).`);
       return;
     }
   } catch (err) {
+    if (err && typeof err.message === "string" && err.message.startsWith("SECURITY:")) {
+      console.error(err.message);
+      process.exit(1);
+    }
     lastErr = err;
   }
 
@@ -158,4 +258,8 @@ async function main() {
   process.exit(0);
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseSHA256Line, downloadWithHash, verifySHA256 };

package/npm/postinstall.test.js

@@ -0,0 +1,112 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+const { parseSHA256Line } = require("./postinstall");
+
+test("parseSHA256Line: returns hash for matching filename in single-line content", () => {
+  const content = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789  nano-brain-linux-amd64\n";
+  assert.strictEqual(
+    parseSHA256Line(content, "nano-brain-linux-amd64"),
+    "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
+  );
+});
+
+test("parseSHA256Line: returns correct hash with multiple entries", () => {
+  const content = [
+    "1111111111111111111111111111111111111111111111111111111111111111  nano-brain-linux-amd64",
+    "2222222222222222222222222222222222222222222222222222222222222222  nano-brain-linux-arm64",
+    "3333333333333333333333333333333333333333333333333333333333333333  nano-brain-darwin-amd64",
+    "4444444444444444444444444444444444444444444444444444444444444444  nano-brain-darwin-arm64",
+    "",
+  ].join("\n");
+  assert.strictEqual(
+    parseSHA256Line(content, "nano-brain-darwin-amd64"),
+    "3333333333333333333333333333333333333333333333333333333333333333",
+  );
+});
+
+test("parseSHA256Line: returns null when filename is not listed", () => {
+  const content = "aaaa111122223333444455556666777788889999aaaabbbbccccddddeeeeffff  nano-brain-linux-amd64\n";
+  assert.strictEqual(parseSHA256Line(content, "nano-brain-windows-amd64"), null);
+});
+
+test("parseSHA256Line: returns null for empty input", () => {
+  assert.strictEqual(parseSHA256Line("", "anything"), null);
+  assert.strictEqual(parseSHA256Line(null, "anything"), null);
+  assert.strictEqual(parseSHA256Line(undefined, "anything"), null);
+});
+
+test("parseSHA256Line: returns null for malformed content (no hex)", () => {
+  assert.strictEqual(parseSHA256Line("not a checksum line\n", "anything"), null);
+  assert.strictEqual(parseSHA256Line("ZZZZ  nano-brain-linux-amd64\n", "nano-brain-linux-amd64"), null);
+});
+
+test("parseSHA256Line: ignores blank lines and unrelated text", () => {
+  const content = [
+    "",
+    "# Comment line that should be ignored",
+    "",
+    "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789  nano-brain-linux-amd64",
+    "",
+  ].join("\n");
+  assert.strictEqual(
+    parseSHA256Line(content, "nano-brain-linux-amd64"),
+    "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
+  );
+});
+
+test("parseSHA256Line: handles CRLF line endings", () => {
+  const content =
+    "1111111111111111111111111111111111111111111111111111111111111111  nano-brain-linux-amd64\r\n" +
+    "2222222222222222222222222222222222222222222222222222222222222222  nano-brain-linux-arm64\r\n";
+  assert.strictEqual(
+    parseSHA256Line(content, "nano-brain-linux-arm64"),
+    "2222222222222222222222222222222222222222222222222222222222222222",
+  );
+});
+
+test("parseSHA256Line: rejects hashes shorter than 64 hex chars", () => {
+  const content = "abc  nano-brain-linux-amd64\n";
+  assert.strictEqual(parseSHA256Line(content, "nano-brain-linux-amd64"), null);
+});
+
+test("parseSHA256Line: filename match is exact, not substring", () => {
+  const content = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789  nano-brain-linux-amd64-extra\n";
+  assert.strictEqual(parseSHA256Line(content, "nano-brain-linux-amd64"), null);
+});
+
+test("parseSHA256Line: hash format is independent of computed digest format", () => {
+  const payload = Buffer.from("the quick brown fox jumps over the lazy dog");
+  const computed = crypto.createHash("sha256").update(payload).digest("hex");
+  const line = `${computed}  testfile\n`;
+  assert.strictEqual(parseSHA256Line(line, "testfile"), computed);
+  assert.strictEqual(
+    parseSHA256Line(line, "testfile").toLowerCase(),
+    computed.toLowerCase(),
+    "hash comparison must be lowercase-insensitive in caller",
+  );
+});
+
+test("end-to-end: full integrity flow with mocked content matches expected hash", () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nb-sha-test-"));
+  try {
+    const fakeBinary = Buffer.from("\x7fELF fake binary contents for test\n".repeat(100));
+    const binPath = path.join(tmpDir, "nano-brain-linux-amd64");
+    fs.writeFileSync(binPath, fakeBinary);
+    const expectedHash = crypto.createHash("sha256").update(fakeBinary).digest("hex");
+    const sumsContent = `${expectedHash}  nano-brain-linux-amd64\n`;
+    const parsed = parseSHA256Line(sumsContent, "nano-brain-linux-amd64");
+    assert.strictEqual(parsed, expectedHash, "parse must round-trip a real SHA-256 hex");
+
+    const corrupted = Buffer.concat([fakeBinary, Buffer.from("X")]);
+    const corruptedHash = crypto.createHash("sha256").update(corrupted).digest("hex");
+    assert.notStrictEqual(corruptedHash, expectedHash, "different content must produce different hash");
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-step/nano-brain",
-  "version": "2026.6.207",
+  "version": "2026.6.209",
   "description": "Persistent memory and code intelligence for AI coding agents",
   "bin": {
     "nano-brain": "npm/run.js"