@nexus-flow/mcp 0.13.0

package/README.md

@@ -0,0 +1,63 @@
+# @nexus-flow/mcp
+
+A tiny **runner shim** that lets an MCP host (Claude Desktop, Cursor, Windsurf, …) start the
+[nexus-flow](https://nxf.nxsflow.com) MCP server **without `nxs` installed first**.
+
+It fetches the signed `nxs` prebuilt for your platform, **verifies it (sha256 + minisign)**,
+caches it, and execs `nxs mcp serve` — passing your arguments through.
+
+## Use it in a host config
+
+```json
+{
+  "mcpServers": {
+    "nxs": {
+      "command": "npx",
+      "args": ["-y", "@nexus-flow/mcp", "--", "--workspace", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+Everything after `--` is passed straight to `nxs mcp serve` (e.g. `--workspace`, `--actor`). If
+you already have `nxs` on `PATH`, point the host at it directly instead — this shim exists for the
+"not installed at all" case (`nxs mcp install` writes the direct entry; `nxs mcp install --runner
+npx` writes the entry above).
+
+## Security
+
+The shim **never execs an unverified binary**. Two gates, both mandatory, both fail-closed:
+
+- **sha256** (integrity) — the `.sha256` sidecar must match the downloaded bytes.
+- **minisign** (authenticity) — a prehashed Ed25519/BLAKE2b-512 signature is verified against the
+  public key **embedded in this package** (the same key `nxs` and `install.sh` use). A tampered
+  tarball, a wrong key, a legacy (un-prehashed) signature, or a missing signature all abort before
+  anything runs. There is **no** insecure-bootstrap escape hatch here.
+
+Verification uses only Node's built-in `crypto` — this package has **zero runtime dependencies**.
+
+Only bytes that passed **both** gates are written into the cache (verify-before-cache, via an atomic
+temp→rename). A cached binary is therefore trusted and exec'd on later launches **without**
+re-verification, so the integrity of the cache directory rests on filesystem permissions — the cache
+lives under your per-user cache dir (or `NXS_MCP_CACHE_DIR`); keep it user-writable only. Downloads
+are bounded (per-request idle timeout, a hard byte cap, and a decompression-size cap) so a stalled or
+malicious origin fails fast instead of hanging or exhausting memory before the gate.
+
+## Configuration (env, matching `install.sh`)
+
+| Variable            | Default                     | Meaning                                      |
+| ------------------- | --------------------------- | -------------------------------------------- |
+| `NXF_CHANNEL`       | `stable`                    | Promotion ring (`stable` / `beta` / `alpha`) |
+| `NXF_VERSION`       | *(newest in channel)*       | Pin an exact version                         |
+| `NXF_BASE_URL`      | `https://nxf.nxsflow.com`   | Artifact origin                              |
+| `NXF_PLATFORM`      | *(auto from os/arch)*       | Override host detection                      |
+| `NXS_MCP_CACHE_DIR` | OS cache dir                | Where the verified `nxs` is cached           |
+
+The first launch downloads and verifies (a few seconds); subsequent launches use the cache and
+start instantly — and work offline.
+
+## Platforms
+
+`{darwin,linux}-{aarch64,x86_64}`. Windows support is tracked upstream.
+
+Requires Node ≥ 18.

package/bin/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+// @nexus-flow/mcp — the runner shim for hosts where `nxs` is not installed. A host MCP config
+// launches `npx -y @nexus-flow/mcp -- <args>`; this fetches the signed `nxs` prebuilt for the
+// platform, VERIFIES it (sha256 + minisign, fail-closed), caches it, and execs `nxs mcp serve`
+// with the host args passed through. stdout is the MCP stdio channel — every diagnostic goes to
+// stderr so it never corrupts the protocol stream.
+
+const { spawn } = require('node:child_process');
+const { ensureNxs } = require('../lib/index');
+
+async function main() {
+  const passthrough = process.argv.slice(2); // e.g. ["--workspace", "/proj"]
+
+  let nxs;
+  try {
+    nxs = await ensureNxs({ env: process.env });
+  } catch (e) {
+    process.stderr.write(`nexus-flow: could not obtain a verified nxs binary: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  // Hand off to the real server. `stdio: 'inherit'` wires the host's stdin/stdout/stderr straight
+  // through to nxs (MCP speaks over stdio). Async spawn (not spawnSync) keeps the event loop free so
+  // a SIGINT/SIGTERM sent to THIS process (a host that signals the node PID directly, not just via
+  // stdin-EOF) is forwarded to nxs instead of leaving it orphaned. Propagate the child's exit code,
+  // or re-raise the terminating signal so callers observe the real cause.
+  const child = spawn(nxs, ['mcp', 'serve', ...passthrough], { stdio: 'inherit' });
+
+  const forward = (sig) => {
+    if (!child.killed) child.kill(sig);
+  };
+  process.on('SIGINT', () => forward('SIGINT'));
+  process.on('SIGTERM', () => forward('SIGTERM'));
+  process.on('SIGHUP', () => forward('SIGHUP'));
+
+  child.on('error', (e) => {
+    process.stderr.write(`nexus-flow: failed to launch nxs: ${e.message}\n`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      // Re-raise so the parent dies of the same signal (128+n exit), the conventional shell contract.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+main();

package/lib/cache.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// resolveCacheDir(env, platform, homedir): the per-user cache root for downloaded binaries. The
+// NXS_MCP_CACHE_DIR override wins (testing / locked-down homes); otherwise the OS convention — macOS
+// ~/Library/Caches, Linux $XDG_CACHE_HOME or ~/.cache.
+function resolveCacheDir(env = process.env, platform = '', homedir = os.homedir()) {
+  if (env.NXS_MCP_CACHE_DIR) return env.NXS_MCP_CACHE_DIR;
+  const os_ = platform.split('-')[0];
+  if (os_ === 'darwin') return path.join(homedir, 'Library', 'Caches', 'nexus-flow', 'mcp');
+  const xdg = env.XDG_CACHE_HOME || path.join(homedir, '.cache');
+  return path.join(xdg, 'nexus-flow', 'mcp');
+}
+
+// The immutable, channel- + version- + platform-scoped path a verified `nxs` lands at. Versions are
+// immutable, so a binary present here was already sha256+minisign-verified before it was moved into
+// place. The `channel` segment keeps the offline fallback from ever serving a binary from a
+// different promotion ring than the one requested (e.g. a cached `beta` for a `stable` run).
+function binaryPath(cacheDir, channel, version, platform) {
+  return path.join(cacheDir, 'nxs', channel, version, platform, 'nxs');
+}
+
+// readCached: the binary path if a verified copy is already cached, else null.
+function readCached(cacheDir, channel, version, platform) {
+  const p = binaryPath(cacheDir, channel, version, platform);
+  return fs.existsSync(p) ? p : null;
+}
+
+// install: write verified bytes to a temp sibling, chmod 0755, then atomically rename into the
+// cache path — a concurrent reader never sees a half-written binary. Returns the final path.
+// Caller MUST have verified the bytes first (only verified bytes are ever passed here).
+function install(cacheDir, channel, version, platform, bytes) {
+  const dest = binaryPath(cacheDir, channel, version, platform);
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.nxs.tmp.${process.pid}`);
+  try {
+    fs.writeFileSync(tmp, bytes, { mode: 0o755 });
+    fs.chmodSync(tmp, 0o755); // writeFileSync mode is subject to umask; force it
+    fs.renameSync(tmp, dest);
+  } catch (e) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw e;
+  }
+  return dest;
+}
+
+module.exports = { resolveCacheDir, binaryPath, readCached, install };

package/lib/constants.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// Embedded minisign PUBLIC key — safe to ship in a world-readable package (it verifies, never
+// signs). MUST stay byte-identical to install.sh's EMBEDDED_MINISIGN_PUBKEY and the release
+// pipeline's vars.NXF_MINISIGN_PUBKEY; the pubkey cross-check in .github/workflows/install-sh-ci.yml
+// fails CI on drift. Rotation = update this one line (and install.sh's, and the repo var).
+const EMBEDDED_MINISIGN_PUBKEY = 'RWRnRFdblE2/DEmkBWpMPqXYele5JoNtQubF+N1Ryp7msJgq7HKn2Ola';
+
+// Public origin serving /latest, /download/*, and the sidecars (install.sh's NXF_BASE_URL default).
+const DEFAULT_BASE_URL = 'https://nxf.nxsflow.com';
+
+// Default promotion ring — the most-stable of release/channels (single source of truth). `cargo
+// xtask channels check` asserts this equals the canonical most-stable channel. The set of shipped
+// platform keys is not duplicated here: lib/platform.js maps the os/arch tokens componentwise (like
+// install.sh's platform_for), and `cargo xtask platforms check` guards that mapping.
+const DEFAULT_CHANNEL = 'stable';
+
+module.exports = { EMBEDDED_MINISIGN_PUBKEY, DEFAULT_BASE_URL, DEFAULT_CHANNEL };

package/lib/download.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+const { sameOrigin } = require('./resolve');
+
+function client(url) {
+  return url.startsWith('https:') ? https : http;
+}
+
+// Idle-socket timeout for a single GET: fires when no bytes arrive for this long (it RESETS on
+// activity, so a large-but-flowing download never trips it — only a stall / hung TLS does). Bounds
+// the slow-loris case where a CDN accepts then goes silent.
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// Hard cap on a single response body. The largest legitimate artifact is one tarball (nxs +
+// nxf-relay + docs, tens of MB); this ceiling is comfortably above that but stops a malicious /
+// compromised origin from OOM-ing startup by streaming unbounded bytes BEFORE verification.
+const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+
+// One GET, no redirect following, resolving to { statusCode, location, body }. Rejects on a
+// transport/TLS error, on an idle timeout, or when the body exceeds `maxBytes` — every real HTTP
+// status is a resolved value the caller decides on.
+function request(url, { timeoutMs = DEFAULT_TIMEOUT_MS, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = client(url).get(url, (res) => {
+      const chunks = [];
+      let total = 0;
+      res.on('data', (c) => {
+        total += c.length;
+        if (total > maxBytes) {
+          // Refuse before buffering more: this runs pre-verification, so an unbounded body must
+          // never be allowed to exhaust memory.
+          req.destroy();
+          reject(new Error(`response from ${url} is too large (exceeds ${maxBytes} bytes) — refusing`));
+          return;
+        }
+        chunks.push(c);
+      });
+      res.on('end', () =>
+        resolve({
+          statusCode: res.statusCode,
+          location: res.headers.location,
+          body: Buffer.concat(chunks),
+        })
+      );
+    });
+    // Idle timeout on the underlying socket (covers connect-then-stall and never-respond alike).
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error(`request to ${url} timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+  });
+}
+
+// resolveRedirect(url): return the Location of a single 3xx WITHOUT following it (so the caller can
+// same-origin-check the server-controlled target before fetching). null on a genuine 404 (nothing
+// published); throw on any other status, an idle timeout, or a transport error — a dropped/blocked
+// request must NOT read as "not found" and silently downgrade.
+async function resolveRedirect(url, opts = {}) {
+  const { statusCode, location } = await request(url, opts);
+  if (statusCode >= 300 && statusCode < 400 && location) return location;
+  if (statusCode === 404) return null;
+  throw new Error(`unexpected HTTP ${statusCode} resolving ${url}`);
+}
+
+// download(url): GET the bytes, following redirects (bounded), rejecting on a non-2xx final status,
+// an idle timeout, or an oversized body. Redirect hops are same-origin-guarded against the ORIGINAL
+// url (rejecting a cross-host jump or an https→http downgrade): minisign is the real integrity
+// backstop, but there is no reason to follow a server-directed fetch off our own origin.
+async function download(url, { maxRedirects = 5, timeoutMs, maxBytes } = {}) {
+  const reqOpts = {};
+  if (timeoutMs !== undefined) reqOpts.timeoutMs = timeoutMs;
+  if (maxBytes !== undefined) reqOpts.maxBytes = maxBytes;
+  let current = url;
+  for (let i = 0; i <= maxRedirects; i++) {
+    const { statusCode, location, body } = await request(current, reqOpts);
+    if (statusCode >= 200 && statusCode < 300) return body;
+    if (statusCode >= 300 && statusCode < 400 && location) {
+      const next = new URL(location, current).toString();
+      if (!sameOrigin(next, url)) {
+        throw new Error(`refusing cross-origin/downgraded redirect from ${url} to ${next}`);
+      }
+      current = next;
+      continue;
+    }
+    throw new Error(`download failed: HTTP ${statusCode} for ${current}`);
+  }
+  throw new Error(`download failed: too many redirects for ${url}`);
+}
+
+module.exports = { resolveRedirect, download, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES };

package/lib/extract.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const zlib = require('node:zlib');
+
+const BLOCK = 512;
+
+// Cap on the INFLATED tar size. Well above a real release (nxs + nxf-relay + docs, tens of MB) yet
+// bounded, so a decompression bomb (a tiny gzip that inflates to gigabytes) throws instead of
+// exhausting memory. This runs before verification only for the tarball path already byte-capped in
+// download.js — defense in depth on the two DoS surfaces the review flagged.
+const DEFAULT_MAX_OUTPUT = 512 * 1024 * 1024;
+
+// Read the NUL-terminated name from a ustar header block (bytes 0..100). Release tarballs ship bare
+// member names (`nxs`, `nxf-relay`, …), all well under 100 chars, so the `prefix` field is never
+// needed here.
+function headerName(block) {
+  const raw = block.subarray(0, 100);
+  const nul = raw.indexOf(0);
+  return raw.toString('latin1', 0, nul === -1 ? 100 : nul);
+}
+
+// Parse the octal size field (bytes 124..136).
+function headerSize(block) {
+  const raw = block.subarray(124, 136).toString('latin1').replace(/[\0 ]+$/g, '').trim();
+  return raw ? parseInt(raw, 8) : 0;
+}
+
+// extractMember(tarGzBuffer, name): gunzip and walk the tar, returning the exact bytes of the
+// regular-file member matching `name`. Extracting a single member by EXACT name (not a wildcard)
+// also defeats any `../`/absolute-path entry a tampered tarball might carry — defense in depth
+// behind the sha256 + minisign gates. Throws if the member is absent.
+function extractMember(tarGzBuffer, name, { maxOutputLength = DEFAULT_MAX_OUTPUT } = {}) {
+  // `maxOutputLength` makes gunzip throw (RangeError) rather than inflate an unbounded bomb.
+  const tar = zlib.gunzipSync(tarGzBuffer, { maxOutputLength });
+  let pos = 0;
+  while (pos + BLOCK <= tar.length) {
+    const header = tar.subarray(pos, pos + BLOCK);
+    const entryName = headerName(header);
+    if (entryName === '') break; // end-of-archive marker (zero block)
+    const size = headerSize(header);
+    const typeflag = header[156];
+    const dataStart = pos + BLOCK;
+    // Regular file: typeflag '0' (0x30) or NUL (legacy).
+    if (entryName === name && (typeflag === 0x30 || typeflag === 0)) {
+      return Buffer.from(tar.subarray(dataStart, dataStart + size));
+    }
+    pos = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  throw new Error(`member '${name}' not found in the downloaded tarball`);
+}
+
+module.exports = { extractMember };

package/lib/index.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { detectPlatform } = require('./platform');
+const { resolveCacheDir, binaryPath, readCached, install } = require('./cache');
+const { pinnedUrl, latestUrl, sidecarUrls, sameOrigin } = require('./resolve');
+const { resolveRedirect, download } = require('./download');
+const { verifySha256, verifyMinisign } = require('./verify');
+const { extractMember } = require('./extract');
+const { EMBEDDED_MINISIGN_PUBKEY, DEFAULT_BASE_URL, DEFAULT_CHANNEL } = require('./constants');
+
+// Plain-SemVer shape a version must match (matches release/version's `X.Y.Z`, no suffixes).
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+// A security refusal that must NEVER be papered over by the offline cache fallback (an off-origin
+// /latest redirect). A typed sentinel, so the catch below matches on the type — not on error text.
+class OriginRefusedError extends Error {}
+
+// Parse the version out of `nxf_<version>_<platform>.tar.gz`.
+function versionFromTarballName(name, platform) {
+  const m = new RegExp(`^nxf_(.+)_${platform.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.tar\\.gz$`).exec(name);
+  if (!m) throw new Error(`unexpected tarball name '${name}' (cannot read version)`);
+  return m[1];
+}
+
+// Compare two plain-SemVer strings (X.Y.Z) descending.
+function semverDesc(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pb[i] || 0) !== (pa[i] || 0)) return (pb[i] || 0) - (pa[i] || 0);
+  }
+  return 0;
+}
+
+// The newest already-cached, already-verified binary for this channel + platform, or null. Used as
+// an offline fallback when the CDN is unreachable. Scoped to `channel` so a `stable` run never falls
+// back to a `beta` binary cached earlier.
+function newestCached(cacheDir, channel, platform) {
+  const root = path.join(cacheDir, 'nxs', channel);
+  let versions;
+  try {
+    versions = fs.readdirSync(root);
+  } catch {
+    return null;
+  }
+  const usable = versions
+    .filter((v) => VERSION_RE.test(v) && fs.existsSync(binaryPath(cacheDir, channel, v, platform)))
+    .sort(semverDesc);
+  return usable.length
+    ? { version: usable[0], path: binaryPath(cacheDir, channel, usable[0], platform) }
+    : null;
+}
+
+// ensureNxs(opts): resolve → download → VERIFY (sha256 + minisign, fail-closed) → extract → cache
+// the signed `nxs` binary, returning its path. All logging is on the caller-supplied `log` (the CLI
+// routes it to stderr — stdout is the MCP channel). Options default to production values; tests
+// inject a fixture base URL, platform, pubkey, and cache dir.
+async function ensureNxs(opts = {}) {
+  const env = opts.env || process.env;
+  const log = opts.log || ((m) => process.stderr.write(`${m}\n`));
+  const baseUrl = opts.baseUrl || env.NXF_BASE_URL || DEFAULT_BASE_URL;
+  const channel = opts.channel || env.NXF_CHANNEL || DEFAULT_CHANNEL;
+  const platform = opts.platform || detectPlatform(env);
+  const pubkey = opts.pubkey || EMBEDDED_MINISIGN_PUBKEY;
+  const cacheDir = opts.cacheDir || resolveCacheDir(env, platform);
+  const pinnedVersion = opts.version || env.NXF_VERSION || null;
+
+  // Validate a pinned version up front: it is interpolated into the cache path and the download URL,
+  // so a malformed value (e.g. `../../..`) must be rejected outright rather than traversing the cache
+  // dir. Same plain-SemVer shape enforced for a version discovered from `/latest`.
+  if (pinnedVersion && !VERSION_RE.test(pinnedVersion)) {
+    throw new Error(`invalid pinned version '${pinnedVersion}' (expected plain SemVer X.Y.Z)`);
+  }
+
+  // A pinned + cached version needs no network at all.
+  if (pinnedVersion) {
+    const hit = readCached(cacheDir, channel, pinnedVersion, platform);
+    if (hit) {
+      log(`nexus-flow: using cached nxs ${pinnedVersion} (${channel}, ${platform})`);
+      return hit;
+    }
+  }
+
+  // Resolve the tarball URL + concrete version. On any resolution failure, fall back to the newest
+  // cached binary (offline resilience) before giving up.
+  let tarUrl;
+  let version;
+  try {
+    if (pinnedVersion) {
+      version = pinnedVersion;
+      tarUrl = pinnedUrl(baseUrl, channel, version, platform);
+    } else {
+      const resolved = await resolveRedirect(latestUrl(baseUrl, channel, platform));
+      if (!resolved) throw new Error(`no release published for ${platform} on channel '${channel}'`);
+      if (!sameOrigin(resolved, baseUrl)) {
+        throw new OriginRefusedError(`refusing /latest redirect to a different origin: ${resolved}`);
+      }
+      tarUrl = resolved;
+      version = versionFromTarballName(path.posix.basename(new URL(tarUrl).pathname), platform);
+      const hit = readCached(cacheDir, channel, version, platform);
+      if (hit) {
+        log(`nexus-flow: using cached nxs ${version} (${channel}, ${platform})`);
+        return hit;
+      }
+    }
+  } catch (e) {
+    // An off-origin redirect is a security refusal, never something to paper over with the cache.
+    if (e instanceof OriginRefusedError) throw e;
+    const fb = newestCached(cacheDir, channel, platform);
+    if (fb) {
+      log(
+        `nexus-flow: warning: could not reach ${baseUrl} (${e.message}); using cached nxs ${fb.version} (${channel})`
+      );
+      return fb.path;
+    }
+    throw e;
+  }
+
+  // Download the tarball + both sidecars. A missing sidecar (download throws on non-2xx) aborts —
+  // there is no downgrade to sha256-only and no unsigned path.
+  log(`nexus-flow: downloading ${tarUrl}`);
+  const { sha256: shaUrl, minisig: sigUrl } = sidecarUrls(tarUrl);
+  const [tarball, shaText, sigText] = await Promise.all([
+    download(tarUrl),
+    download(shaUrl),
+    download(sigUrl),
+  ]);
+
+  // Both gates are mandatory; either throws → nothing is extracted or cached.
+  verifySha256(tarball, shaText.toString('utf8'));
+  verifyMinisign(tarball, sigText.toString('utf8'), pubkey);
+  log('nexus-flow: signature verified');
+
+  const bin = extractMember(tarball, 'nxs');
+  const p = install(cacheDir, channel, version, platform, bin);
+  log(`nexus-flow: installed nxs ${version} → ${p}`);
+  return p;
+}
+
+module.exports = { ensureNxs, versionFromTarballName, newestCached, OriginRefusedError };

package/lib/platform.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Host → canonical platform key. Mirrors install.sh's `platform_for` (and decide.ts's
+// normalizeOs/normalizeArch): the shim is a componentwise consumer of release/platforms, the
+// single source of truth for the four shipped targets. `cargo xtask platforms check` asserts the
+// mapping below covers every canonical os/arch token, so a 5th target or a rename fails CI here.
+
+// uname os token → canonical os.
+function osFor(unameS) {
+  switch (unameS) {
+    case 'Darwin':
+      return 'darwin';
+    case 'Linux':
+      return 'linux';
+    default:
+      return null;
+  }
+}
+
+// uname machine token → canonical arch (forgiving on synonyms).
+function archFor(unameM) {
+  switch (unameM) {
+    case 'arm64':
+    case 'aarch64':
+      return 'aarch64';
+    case 'x86_64':
+    case 'amd64':
+      return 'x86_64';
+    default:
+      return null;
+  }
+}
+
+// platformFor(unameS, unameM) → "<os>-<arch>" for a shipped target, else null.
+function platformFor(unameS, unameM) {
+  const os = osFor(unameS);
+  const arch = archFor(unameM);
+  if (!os || !arch) return null;
+  return `${os}-${arch}`;
+}
+
+// Node's process.platform → the uname `-s` token platformFor understands.
+function unameSFor(nodePlatform) {
+  switch (nodePlatform) {
+    case 'darwin':
+      return 'Darwin';
+    case 'linux':
+      return 'Linux';
+    default:
+      return nodePlatform; // unrecognised → platformFor returns null → detectPlatform throws
+  }
+}
+
+// Node's process.arch → a uname `-m` token platformFor understands ('x64' → 'x86_64'; 'arm64'
+// passes through since archFor already accepts it).
+function unameMFor(nodeArch) {
+  return nodeArch === 'x64' ? 'x86_64' : nodeArch;
+}
+
+// Resolve the platform key: the NXF_PLATFORM override (escape hatch / testing) wins; otherwise
+// derive from the node os/arch tokens. Throws a clear message on an unsupported host rather than
+// letting a 404 surface three steps later.
+function detectPlatform(env, nodePlatform = process.platform, nodeArch = process.arch) {
+  if (env && env.NXF_PLATFORM) return env.NXF_PLATFORM;
+  const platform = platformFor(unameSFor(nodePlatform), unameMFor(nodeArch));
+  if (!platform) {
+    throw new Error(
+      `unsupported platform: ${nodePlatform}/${nodeArch}. Supported: {darwin,linux}-{aarch64,x86_64}.`
+    );
+  }
+  return platform;
+}
+
+module.exports = { platformFor, detectPlatform };

package/lib/resolve.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// Pure URL construction for the artifact CDN. The network round-trips (fetch, follow the /latest
+// 302) live in download.js/index.js; this module stays side-effect-free and unit-testable.
+
+function stripSlash(base) {
+  return base.replace(/\/+$/, '');
+}
+
+// `nxf_<version>_<platform>.tar.gz` — the release packaging name (release.yml).
+function tarballName(version, platform) {
+  return `nxf_${version}_${platform}.tar.gz`;
+}
+
+// The immutable per-version artifact path (used when NXF_VERSION pins a version).
+function pinnedUrl(baseUrl, channel, version, platform) {
+  return `${stripSlash(baseUrl)}/download/${channel}/${version}/${tarballName(version, platform)}`;
+}
+
+// /latest?channel=&target=&arch= → 302 to the newest channel tarball. `platform` is the "<os>-<arch>"
+// key; target/arch are its two halves (os and arch each carry no '-').
+function latestUrl(baseUrl, channel, platform) {
+  const [os, arch] = platform.split('-');
+  return `${stripSlash(baseUrl)}/latest?channel=${channel}&target=${os}&arch=${arch}`;
+}
+
+// The `.sha256` / `.minisig` sidecars sit next to the resolved tarball.
+function sidecarUrls(tarUrl) {
+  return { sha256: `${tarUrl}.sha256`, minisig: `${tarUrl}.minisig` };
+}
+
+// sameOrigin(url, base): true iff `url` has the same scheme://authority as `base`. Guards the
+// server-controlled /latest redirect target against an open-redirect off our origin or an http
+// downgrade before we fetch it.
+function sameOrigin(url, base) {
+  try {
+    const a = new URL(url);
+    const b = new URL(base);
+    return a.protocol === b.protocol && a.host === b.host;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { tarballName, pinnedUrl, latestUrl, sidecarUrls, sameOrigin };

package/lib/verify.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+// Two-gate download verification, ported faithfully from install.sh (§5.3) — but fail-closed
+// UNCONDITIONALLY: this is the binary-exec path, so there is no NXF_INSECURE escape hatch and no
+// 404-signature downgrade. sha256 proves INTEGRITY; minisign proves AUTHENTICITY. Any failure in
+// either throws, and the caller must never exec an unverified binary.
+
+// The fixed 12-byte SPKI DER header that wraps a raw Ed25519 public key so `crypto.createPublicKey`
+// can import it (identical bytes to install.sh's `\060\052\060\005\006\003\053\145\160\003\041\000`).
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+// Strict base64 decode: reject anything outside the base64 alphabet BEFORE decoding (Node's decoder
+// silently drops invalid chars, which would weaken the length checks below).
+function strictBase64(s, what) {
+  const trimmed = String(s).trim();
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(trimmed)) {
+    throw new Error(`${what} is not valid base64 (refusing to verify)`);
+  }
+  return Buffer.from(trimmed, 'base64');
+}
+
+// verifySha256(buf, sidecarText): MANDATORY integrity gate. The sidecar is `<hex>  <name>`
+// (publish-release.sh); compare only the hex so a name mismatch cannot weaken it.
+function verifySha256(buf, sidecarText) {
+  const expected = String(sidecarText).trim().split(/\s+/)[0];
+  if (!expected) throw new Error('empty sha256 sidecar (refusing to install)');
+  const actual = crypto.createHash('sha256').update(buf).digest('hex');
+  if (expected.toLowerCase() !== actual) {
+    throw new Error(`sha256 mismatch — expected ${expected}, got ${actual} (refusing to install)`);
+  }
+}
+
+// Take the base64 body of a minisign public key: accept a bare base64 line OR a full minisign.pub
+// (comment + base64), exactly as install.sh's openssl path does — the last non-comment, non-blank
+// line.
+function pubkeyBody(pubkeyText) {
+  const lines = String(pubkeyText)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('untrusted comment:'));
+  if (lines.length === 0) throw new Error('minisign public key is empty (refusing to verify)');
+  return lines[lines.length - 1];
+}
+
+// verifyMinisign(buf, minisigText, pubkeyText): MANDATORY authenticity gate. Verifies a prehashed
+// (minisign `-H`) Ed25519/BLAKE2b-512 signature — the only form the release pipeline emits and the
+// only form accepted here (a legacy un-prehashed "Ed" signature is refused, never verified on a
+// different path). Throws on any failure.
+function verifyMinisign(buf, minisigText, pubkeyText) {
+  // Public key: 2-byte algorithm + 8-byte key id + 32-byte Ed25519 key = 42 bytes.
+  const pub = strictBase64(pubkeyBody(pubkeyText), 'minisign public key');
+  if (pub.length !== 42) {
+    throw new Error('minisign public key has an unexpected length (refusing to verify)');
+  }
+  const pubKeyId = pub.subarray(2, 10);
+  const rawKey = pub.subarray(10, 42);
+
+  // Signature: line 2 of the .minisig — 2-byte algorithm + 8-byte key id + 64-byte signature.
+  const sigLine = String(minisigText).split('\n')[1];
+  if (!sigLine || !sigLine.trim()) {
+    throw new Error('minisign .minisig has no signature line (refusing to install)');
+  }
+  const sig = strictBase64(sigLine, 'minisign signature');
+  if (sig.length !== 74) {
+    throw new Error('minisign signature has an unexpected length (refusing to install)');
+  }
+  // Algorithm bytes: "ED" = prehashed (what release.yml produces and what this shim requires).
+  // Anything else (e.g. legacy "Ed") is refused here rather than verified on a different code path.
+  const alg = sig.subarray(0, 2).toString('latin1');
+  if (alg !== 'ED') {
+    throw new Error(
+      'minisign signature is not the prehashed (-H) form this shim verifies (refusing to downgrade)'
+    );
+  }
+  // The signature's key id must match the configured public key's, exactly as minisign checks.
+  if (!crypto.timingSafeEqual(sig.subarray(2, 10), pubKeyId)) {
+    throw new Error('minisign signature key id does not match the configured public key (refusing to install)');
+  }
+  const signature = sig.subarray(10, 74);
+
+  // Message = BLAKE2b-512 of the file (the minisign `-H` prehash), verified with pure Ed25519.
+  const digest = crypto.createHash('blake2b512').update(buf).digest();
+  let ok;
+  try {
+    const key = crypto.createPublicKey({
+      key: Buffer.concat([ED25519_SPKI_PREFIX, rawKey]),
+      format: 'der',
+      type: 'spki',
+    });
+    ok = crypto.verify(null, digest, key, signature);
+  } catch {
+    ok = false;
+  }
+  if (!ok) {
+    throw new Error('minisign signature verification FAILED (refusing to install)');
+  }
+}
+
+module.exports = { verifySha256, verifyMinisign };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@nexus-flow/mcp",
+  "version": "0.13.0",
+  "description": "Runner shim: fetch, verify (sha256 + minisign), cache, and exec the signed nxs binary as an MCP server for hosts where nxs is not installed.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nexus-flow",
+    "nxs"
+  ],
+  "homepage": "https://nxf.nxsflow.com",
+  "bugs": "https://github.com/nxsflow/nexus-flow/issues",
+  "license": "Apache-2.0 OR MIT",
+  "type": "commonjs",
+  "bin": {
+    "nexus-flow-mcp": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}