pi-courier 0.1.37 → 0.1.38

package/README.md

@@ -56,7 +56,7 @@ npm run build
 npm link          # make the `pi-courier` command available globally
 ```
 
-**Do not use `--ignore-scripts`**: the Matrix E2EE library downloads its native binary via postinstall. On npm >= 11 the `allow-scripts` default may block that dependency's postinstall; `pi-courier`'s own postinstall self-checks for it and auto-downloads the missing native binary (one extra download on first install). If you still hit `Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs-linux-x64-gnu'` (e.g. the auto-download was skipped), run manually:
+**Do not use `--ignore-scripts`**: the Matrix E2EE library downloads its native binary via postinstall. On npm >= 11 the `allow-scripts` default may block that dependency's postinstall; `pi-courier`'s own postinstall self-checks for it and auto-downloads the missing native binary (one extra download on first install; since 0.1.38 the binary is cached locally and sha256-verified, so later updates skip the 21 MB download and tampered binaries are refused). If you still hit `Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs-linux-x64-gnu'` (e.g. the auto-download was skipped), run manually:
 
 ```bash
 cd node_modules/@matrix-org/matrix-sdk-crypto-nodejs

package/README.zh-CN.md

@@ -56,7 +56,7 @@ npm run build
 npm link          # 让 `pi-courier` 命令全局可用
 ```
 
-**不要用 `--ignore-scripts`**:Matrix E2EE 库的 postinstall 会下载原生二进制。npm >= 11 的 `allow-scripts` 默认可能拦截该依赖的 postinstall;`pi-courier` 自己的 postinstall 会自检并**自动补下**缺失的原生二进制(首次安装多下载一次)。若仍报 `Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs-linux-x64-gnu'`(比如自检被跳过),再手动补:
+**不要用 `--ignore-scripts`**:Matrix E2EE 库的 postinstall 会下载原生二进制。npm >= 11 的 `allow-scripts` 默认可能拦截该依赖的 postinstall;`pi-courier` 自己的 postinstall 会自检并**自动补下**缺失的原生二进制(首次安装多下载一次;0.1.38 起副本缓存到本地并做 sha256 校验,后续更新免重下,校验不符的库会被拒绝加载)。若仍报 `Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs-linux-x64-gnu'`(比如自检被跳过),再手动补:
 
 ```bash
 cd node_modules/@matrix-org/matrix-sdk-crypto-nodejs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-courier",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "Run pi coding agent from Matrix. Slash commands, skills and prompts fully work from messengers via the RPC protocol.",
   "type": "module",
   "main": "dist/standalone.js",

package/scripts/crypto-native-hashes.json

@@ -0,0 +1,3 @@
+{
+  "0.4.0/matrix-sdk-crypto.linux-x64-gnu": "7078d4dd987128f79afd192c4f621f64adece37e43f2a8756f1d0a9f034de718"
+}

package/scripts/ensure-crypto-native.d.mts

@@ -4,6 +4,42 @@ export interface EnsureResult {
   ok: boolean;
   downloaded?: boolean;
   reason?: string;
+  /** True when the binding was restored from the local cache (no download). */
+  restoredFromCache?: boolean;
+  /** How the binary's sha256 was checked: manifest match, TOFU accept, or rejected. */
+  verified?: "manifest" | "tofu" | "rejected";
+}
+
+/** Options for ensureCryptoNative(); all optional, defaulting to real resolution. */
+export interface EnsureCryptoNativeOptions {
+  cryptoDir?: string | null;
+  basename?: string | null;
+  cacheRoot?: string;
+  manifestPath?: string;
+  runDownloader?: (cryptoDir: string) => void;
+}
+
+/** Cache entry layout under the cache root. */
+export interface CacheEntryPaths {
+  dir: string;
+  nodePath: string;
+  shaPath: string;
+}
+
+/** Result of evaluating a cache entry (readCacheEntry). */
+export interface CacheEntryResult {
+  hit: boolean;
+  nodePath?: string;
+  sha256?: string;
+  verified?: "manifest" | "tofu";
+  reason?: "absent" | "unreadable" | "sidecar-missing" | "sidecar-mismatch" | "manifest-mismatch";
+}
+
+/** Verdict of verifyDownloadedBinding against the sha256 manifest. */
+export interface VerifyDownloadedResult {
+  verdict: "manifest-match" | "manifest-mismatch" | "manifest-miss";
+  observed: string;
+  expected: string | null;
 }
 
 export function nativeBindingBasename(): string | null;
@@ -16,4 +52,51 @@ export function isNativeBindingMissing(cryptoDir: string, basename: string | nul
 
 export function runNativeDownloader(cryptoDir: string): void;
 
-export function ensureCryptoNative(): EnsureResult;
+export function defaultCacheRoot(
+  env?: Record<string, string | undefined>,
+  home?: string
+): string;
+
+export function defaultManifestPath(): string;
+
+export function cacheEntryPaths(
+  cacheRoot: string,
+  version: string,
+  basename: string
+): CacheEntryPaths;
+
+export function sha256FileSync(filePath: string): string;
+
+export function readCryptoPackageVersion(cryptoDir: string): string | null;
+
+/** Returns {} on missing/malformed manifest (warns); never throws. */
+export function readManifest(manifestPath: string): Record<string, string>;
+
+export function readCacheEntry(
+  cacheRoot: string,
+  version: string,
+  basename: string,
+  manifest: Record<string, string>
+): CacheEntryResult;
+
+export function writeCacheEntry(
+  cacheRoot: string,
+  version: string,
+  basename: string,
+  sourceNodePath: string,
+  observedSha256: string
+): void;
+
+export function restoreBindingFromCache(
+  cryptoDir: string,
+  basename: string,
+  cacheNodePath: string
+): string;
+
+export function verifyDownloadedBinding(
+  nodePath: string,
+  manifestKey: string | null,
+  manifest: Record<string, string>
+): VerifyDownloadedResult;
+
+export function ensureCryptoNative(options?: EnsureCryptoNativeOptions): EnsureResult;

package/scripts/ensure-crypto-native.mjs

@@ -18,15 +18,55 @@
  * present before first run. Any failure here degrades to a warning; it never
  * fails the install (the bridge can still run without E2EE crypto).
  *
+ * LOCAL CACHE + SHA256 VERIFICATION (issue #48):
+ *
+ * Every `npm update` reinstalls the dependency tree and wipes the freshly
+ * downloaded .node, forcing a ~21MB re-download (≈1min behind slow proxies).
+ * To avoid that, a verified copy is kept under
+ * `$XDG_CACHE_HOME/pi-courier/native-crypto/<crypto version>/<basename>.node`
+ * (default `~/.cache/pi-courier/native-crypto/...`) with a `<basename>.sha256`
+ * sidecar recording the observed digest. When a later install finds the
+ * binding missing, the cache is consulted first (sidecar + manifest both
+ * verified before use) and restored with zero network traffic.
+ *
+ * Integrity: binaries are loaded by Node as native code, so a tampered
+ * download is arbitrary code execution. Every accepted binary's sha256 must
+ * match `scripts/crypto-native-hashes.json` (keyed `<version>/<basename>`).
+ * A listed version with a mismatching digest is DELETED and E2EE degrades —
+ * the binary is never loaded. An unlisted version is accepted TOFU-style with
+ * a loud warning asking the maintainer to record the digest. Cache entries
+ * whose sidecar disagrees with their bytes are treated as absent.
+ *
+ * All functions are pure-ish (explicit path/manifest params, injectable
+ * downloader) so tests can exercise every branch in temp dirs without network.
+ *
  * Usage (from package root): node scripts/ensure-crypto-native.mjs
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 
+const LOG_PREFIX = "[pi-courier]";
+const CACHE_SUBDIR = join("pi-courier", "native-crypto");
+const MANIFEST_FILENAME = "crypto-native-hashes.json";
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
 /** Current platform/arch names as napi-rs names them (no .node suffix). */
 export function nativeBindingBasename() {
   const { platform, arch } = process;
@@ -108,40 +148,328 @@ export function runNativeDownloader(cryptoDir) {
   });
 }
 
-export function ensureCryptoNative() {
-  const basename = nativeBindingBasename();
-  const cryptoDir = resolveCryptoPackageDir();
+// ---------------------------------------------------------------------------
+// Local cache + sha256 manifest (issue #48)
+// ---------------------------------------------------------------------------
+
+/** Cache root: $XDG_CACHE_HOME/pi-courier/native-crypto, else ~/.cache/… */
+export function defaultCacheRoot(env = process.env, home = homedir()) {
+  const xdg = env.XDG_CACHE_HOME;
+  const base = typeof xdg === "string" && xdg.trim() !== "" ? xdg : join(home, ".cache");
+  return join(base, CACHE_SUBDIR);
+}
+
+/** Manifest ships next to this script (package.json `files` covers scripts/). */
+export function defaultManifestPath() {
+  return fileURLToPath(new URL(`./${MANIFEST_FILENAME}`, import.meta.url));
+}
+
+/** Cache layout: `<cacheRoot>/<version>/<basename>.node` + `<basename>.sha256`. */
+export function cacheEntryPaths(cacheRoot, version, basename) {
+  const dir = join(cacheRoot, version);
+  const nodePath = join(dir, `${basename}.node`);
+  return { dir, nodePath, shaPath: join(dir, `${basename}.sha256`) };
+}
+
+/** sha256 of a file's bytes, lowercase hex. */
+export function sha256FileSync(filePath) {
+  return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+
+/** The crypto package's own version (cache namespace), or null if unreadable. */
+export function readCryptoPackageVersion(cryptoDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(`${cryptoDir}/package.json`, "utf8"));
+    return typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the sha256 manifest. Any problem (missing, malformed, wrong shape)
+ * degrades to an empty manifest — i.e. "nothing is listed", which makes the
+ * flow take the TOFU path instead of ever throwing during install.
+ */
+export function readManifest(manifestPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `${LOG_PREFIX} crypto hash manifest unreadable at ${manifestPath} (${message}) — ` +
+        `treating every version as unlisted (TOFU).`
+    );
+    return {};
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    console.warn(
+      `${LOG_PREFIX} crypto hash manifest malformed at ${manifestPath} — ` +
+        `treating every version as unlisted (TOFU).`
+    );
+    return {};
+  }
+  return parsed;
+}
+
+function manifestLookup(manifest, key) {
+  if (key === null) return { listed: false };
+  if (!Object.prototype.hasOwnProperty.call(manifest, key)) return { listed: false };
+  const expected = String(manifest[key]).trim().toLowerCase();
+  return { listed: true, expected: SHA256_HEX.test(expected) ? expected : null };
+}
+
+function manifestNag(key, observedSha256) {
+    console.warn(
+      `${LOG_PREFIX} crypto binding ${key} is NOT in the sha256 manifest ` +
+        `(scripts/${MANIFEST_FILENAME}, observed sha256 ${observedSha256}) — ` +
+        `accepted this once (TOFU). ` +
+        `Please record that digest so future installs verify against it.`
+    );
+}
+
+/** tmp path for an atomic write; process-unique and random to survive races. */
+function tmpPathFor(destPath) {
+  return `${destPath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+}
+
+/** Write via temp file + atomic rename so an interrupt never leaves half a file. */
+function atomicWrite(destPath, write, mode) {
+  const tmp = tmpPathFor(destPath);
+  try {
+    write(tmp);
+    chmodSync(tmp, mode);
+    renameSync(tmp, destPath);
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      // best effort — the tmp residue is inert
+    }
+    throw err;
+  }
+}
+
+/**
+ * Copy a verified .node into the cache: `<version>/<basename>.node` plus a
+ * `<basename>.sha256` sidecar with the observed digest. Dir 0700, files 0600,
+ * both written atomically (sidecar last: a torn write at worst drops the
+ * sidecar, and a cache entry without a sidecar is treated as absent).
+ */
+export function writeCacheEntry(cacheRoot, version, basename, sourceNodePath, observedSha256) {
+  const { dir, nodePath, shaPath } = cacheEntryPaths(cacheRoot, version, basename);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700); // mkdir mode is umask-filtered; pin it explicitly
+  atomicWrite(nodePath, (tmp) => copyFileSync(sourceNodePath, tmp), 0o600);
+  atomicWrite(shaPath, (tmp) => writeFileSync(tmp, `${observedSha256}\n`), 0o600);
+}
+
+/**
+ * Evaluate the cache entry for `<version>/<basename>` without using it yet.
+ *
+ * A hit requires: the .node exists, its sha256 matches the sidecar, AND (when
+ * the version is listed in the manifest) the manifest digest too. Anything
+ * else is a miss — the cached copy is not used but also not deleted here.
+ * An unlisted-but-self-consistent entry TOFU-hits with a warning (≤1 per run:
+ * this is called at most once per install).
+ */
+export function readCacheEntry(cacheRoot, version, basename, manifest) {
+  const { nodePath, shaPath } = cacheEntryPaths(cacheRoot, version, basename);
+  if (!existsSync(nodePath)) {
+    return { hit: false, reason: "absent" };
+  }
+  let observed;
+  try {
+    observed = sha256FileSync(nodePath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`${LOG_PREFIX} could not hash cached crypto binding ${nodePath}: ${message}`);
+    return { hit: false, reason: "unreadable" };
+  }
+  let sidecar;
+  try {
+    sidecar = readFileSync(shaPath, "utf8").trim().toLowerCase();
+  } catch {
+    return { hit: false, reason: "sidecar-missing" };
+  }
+  if (!SHA256_HEX.test(sidecar) || sidecar !== observed) {
+    return { hit: false, reason: "sidecar-mismatch", observed };
+  }
+  const key = `${version}/${basename}`;
+  const listed = manifestLookup(manifest, key);
+  if (listed.listed) {
+    if (listed.expected === null || listed.expected !== observed) {
+      return { hit: false, reason: "manifest-mismatch", observed };
+    }
+    return { hit: true, nodePath, sha256: observed, verified: "manifest" };
+  }
+  manifestNag(key, observed);
+  return { hit: true, nodePath, sha256: observed, verified: "tofu" };
+}
+
+/** Atomically copy a verified cache entry back into the crypto package dir. */
+export function restoreBindingFromCache(cryptoDir, basename, cacheNodePath) {
+  const target = `${cryptoDir}/${basename}.node`;
+  atomicWrite(target, (tmp) => copyFileSync(cacheNodePath, tmp), 0o644);
+  return target;
+}
+
+/**
+ * Verify a freshly downloaded binding against the manifest. Pure verdict: the
+ * caller decides what to delete. Verdicts:
+ *   manifest-match   digest matches the manifest — accept.
+ *   manifest-mismatch listed digest differs — caller must DELETE the artifact
+ *                    and degrade E2EE; the binary must never be loaded.
+ *   manifest-miss    version not listed — TOFU accept; caller warns.
+ */
+export function verifyDownloadedBinding(nodePath, manifestKey, manifest) {
+  const observed = sha256FileSync(nodePath);
+  const listed = manifestLookup(manifest, manifestKey);
+  if (!listed.listed) {
+    return { verdict: "manifest-miss", observed, expected: null };
+  }
+  if (listed.expected === null || listed.expected !== observed) {
+    return { verdict: "manifest-mismatch", observed, expected: listed.expected };
+  }
+  return { verdict: "manifest-match", observed, expected: listed.expected };
+}
+
+/**
+ * Orchestration. All inputs are injectable so tests run in temp dirs; the
+ * no-argument call keeps the exact pre-cache behaviour contract:
+ * `{ok, downloaded, reason?}` with failures warned, never thrown.
+ *
+ * @param {{
+ *   cryptoDir?: string | null,
+ *   basename?: string | null,
+ *   cacheRoot?: string,
+ *   manifestPath?: string,
+ *   runDownloader?: (cryptoDir: string) => void,
+ * }} [options]
+ */
+export function ensureCryptoNative(options = {}) {
+  const {
+    cryptoDir = resolveCryptoPackageDir(),
+    basename = nativeBindingBasename(),
+    cacheRoot = defaultCacheRoot(),
+    manifestPath = defaultManifestPath(),
+    runDownloader = runNativeDownloader,
+  } = options;
 
   if (!cryptoDir) {
     console.warn(
-      "[pi-courier] crypto package not found — can't verify native binding; continuing (E2EE may be unavailable)."
+      `${LOG_PREFIX} crypto package not found — can't verify native binding; continuing (E2EE may be unavailable).`
     );
     return { ok: false, reason: "crypto-package-not-found" };
   }
 
   if (!isNativeBindingMissing(cryptoDir, basename)) {
     // Already present (either downloaded once, or platform unsupported).
+    // Deliberately no post-hoc verification of an existing binding.
     return { ok: true, downloaded: false };
   }
 
+  const version = readCryptoPackageVersion(cryptoDir);
+  const manifest = readManifest(manifestPath);
+  const key = version !== null && basename !== null ? `${version}/${basename}` : null;
+
+  // 1) Warm cache: restore a verified copy without touching the network.
+  if (key !== null) {
+    let entry;
+    try {
+      entry = readCacheEntry(cacheRoot, version, basename, manifest);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`${LOG_PREFIX} cache lookup failed: ${message} — falling back to download.`);
+      entry = { hit: false };
+    }
+    if (entry.hit) {
+      try {
+        restoreBindingFromCache(cryptoDir, basename, entry.nodePath);
+        console.info(
+          `${LOG_PREFIX} crypto native binding (${basename}.node) restored from local cache ` +
+            `(${key}, sha256 ${entry.sha256}) — no download needed.`
+        );
+        return { ok: true, downloaded: false, restoredFromCache: true, verified: entry.verified };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `${LOG_PREFIX} could not restore crypto binding from cache: ${message} — falling back to download.`
+        );
+      }
+    }
+  }
+
+  // 2) Cache miss: run the upstream downloader (inherits proxy env).
   console.info(
-    `[pi-courier] crypto native binding (${basename}.node) missing — downloading (POSTINSTALL due to npm 11 allow-scripts).`
+    `${LOG_PREFIX} crypto native binding (${basename}.node) missing — downloading (POSTINSTALL due to npm 11 allow-scripts).`
   );
   try {
-    runNativeDownloader(cryptoDir);
-    return { ok: true, downloaded: true };
+    runDownloader(cryptoDir);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.warn(
-      `[pi-courier] could not auto-download crypto native binding: ${message}\n` +
+      `${LOG_PREFIX} could not auto-download crypto native binding: ${message}\n` +
         `  The bridge may still run without E2EE. To install manually:\n` +
         `  cd ${cryptoDir} && node download-lib.js`
     );
     return { ok: false, reason: "download-failed" };
   }
+
+  // 3) Verify the downloaded binary before accepting it (or caching it).
+  const nodePath = `${cryptoDir}/${basename}.node`;
+  let check;
+  try {
+    check = verifyDownloadedBinding(nodePath, key, manifest);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `${LOG_PREFIX} could not verify downloaded crypto binding (${nodePath}): ${message} — ` +
+        `continuing without it (E2EE may be unavailable).`
+    );
+    return { ok: false, reason: "verify-failed" };
+  }
+
+  if (check.verdict === "manifest-mismatch") {
+    // Never load an unverified native binary. Delete and degrade.
+    try {
+      rmSync(nodePath, { force: true });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`${LOG_PREFIX} could not delete the unverified binding: ${message}`);
+    }
+    console.warn(
+      `${LOG_PREFIX} downloaded crypto binding ${key} FAILED sha256 verification ` +
+        `(expected ${check.expected}, observed ${check.observed}) — file deleted, ` +
+        `continuing WITHOUT native E2EE crypto (the bridge still runs, encrypted ` +
+        `rooms will be unreadable). Possible tampering or upstream asset change.`
+    );
+    return { ok: false, reason: "hash-mismatch", verified: "rejected" };
+  }
+
+  if (check.verdict === "manifest-miss" && key !== null) {
+    manifestNag(key, check.observed);
+  }
+
+  // 4) Best-effort: stash the verified copy for future installs.
+  if (key !== null) {
+    try {
+      writeCacheEntry(cacheRoot, version, basename, nodePath, check.observed);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`${LOG_PREFIX} could not cache the crypto binding: ${message}`);
+    }
+  }
+
+  return {
+    ok: true,
+    downloaded: true,
+    verified: check.verdict === "manifest-match" ? "manifest" : "tofu",
+  };
 }
 
 // Allow running both as a bin and importing the named exports for tests.
 if (process.argv[1] && process.argv[1].endsWith("ensure-crypto-native.mjs")) {
   ensureCryptoNative();
-}
+}