@suveren/gateway 0.11.2 → 0.12.0

package/README.md

@@ -106,7 +106,7 @@ Open `http://localhost:7400`. The MCP server is at `http://localhost:7430`.
 
 ### Option B — npm
 
-Requires [Node.js 20.18.1+](https://nodejs.org/).
+Requires [Node.js 22+](https://nodejs.org/).
 
 ```bash
 npm install -g @suveren/gateway

package/bin/suveren-gateway.js

@@ -20,6 +20,15 @@ import { buildLaunchAgentPlist, buildMacLauncher, buildSystemdUnit, buildWindows
 import { DEFAULT_AS_URL, readConfig, writeConfig, validateAsUrl, validateCaFile, validatePinTls, resolveAsUrl, resolvePinTls, resolvePinTlsExpectedFingerprint, resolveSimulation } from '../lib/config.mjs';
 import { createInterface } from 'node:readline/promises';
 import { readPairing as readAsPairing, recordTlsPin, formatFingerprint, normalizeFingerprint } from '../lib/as-pairing.mjs';
+import { unsupportedNodeReason } from '../lib/node-version.mjs';
+
+// Before any command: on an unsupported Node the connectors cannot run (see
+// lib/node-version.mjs), so refuse with the reason instead of starting.
+const nodeReason = unsupportedNodeReason(process.versions.node);
+if (nodeReason) {
+  console.error(nodeReason);
+  process.exit(1);
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');

package/content/integrations/calendar.json

@@ -9,6 +9,7 @@
     "defaultAgeDays": 30
   },
   "npmPackage": "@humanagencyp/google-calendar-mcp",
+  "npmVersion": "0.1.2",
   "mcp": {
     "command": "google-calendar-mcp",
     "args": []

package/content/integrations/crm.json

@@ -6,6 +6,7 @@
   "icon": "users",
   "profile": "customers",
   "npmPackage": "@humanagencyp/crm-mcp",
+  "npmVersion": "1.1.2",
   "mcp": {
     "command": "crm-mcp",
     "args": []
@@ -142,73 +143,6 @@
       }
     }
   },
-  "templates": [
-    {
-      "name": "Browse & Log",
-      "description": "Search contacts, view pipeline and timeline, log activities. No creates or deletes.",
-      "risk": "low",
-      "mode": "automatic",
-      "bounds": {
-        "read_access": "unlimited",
-        "write_daily_max": "50",
-        "delete_daily_max": "0",
-        "setup_daily_max": "0"
-      },
-      "context": {
-        "contact_type": "customer,lead,partner,vendor"
-      },
-      "intent": "Allow the agent to browse CRM data and log activities. Read and log only — no creating, editing, or deleting records.",
-      "ttl": 2592000,
-      "tags": [
-        "read + log",
-        "no deletes"
-      ]
-    },
-    {
-      "name": "Full CRM with Review",
-      "description": "Create contacts, deals, and tasks. Update and delete records. Every write requires approval.",
-      "risk": "high",
-      "mode": "review",
-      "bounds": {
-        "read_access": "unlimited",
-        "write_daily_max": "50",
-        "delete_daily_max": "10",
-        "setup_daily_max": "0"
-      },
-      "context": {
-        "contact_type": "customer,lead,partner,vendor"
-      },
-      "intent": "Full CRM management — create, update, and delete contacts, deals, and tasks. Every write action requires my review before execution.",
-      "ttl": 2592000,
-      "tags": [
-        "50 writes/day",
-        "10 deletes/day",
-        "review mode"
-      ]
-    },
-    {
-      "name": "Load test data (with approval)",
-      "description": "Load a simulation package (customers and optional contacts) into the simulated CRM, for setting up a three-week test. No browsing, writing, or deleting — this template grants nothing but the one-time test-data load, and it still requires your approval.",
-      "risk": "high",
-      "mode": "review",
-      "bounds": {
-        "read_access": "none",
-        "write_daily_max": "0",
-        "delete_daily_max": "0",
-        "setup_daily_max": "1"
-      },
-      "context": {
-        "contact_type": "customer"
-      },
-      "intent": "Allow the agent to load one simulation package of test data into the simulated CRM, for my review before it happens. No other CRM action is granted by this mandate — set up test data separately from the mandate the agent uses for its actual work.",
-      "ttl": 2592000,
-      "tags": [
-        "setup only",
-        "review mode",
-        "1 load"
-      ]
-    }
-  ],
   "setupHint": "No configuration needed — works out of the box.",
   "setupGuide": [
     {

package/content/integrations/deploy-github.json

@@ -6,12 +6,10 @@
   "icon": "wrench",
   "profile": "deploy",
   "npmPackage": "@humanagencyp/deploy-mcp",
+  "npmVersion": "0.4.2",
   "mcp": {
-    "command": "npx",
-    "args": [
-      "-y",
-      "@humanagencyp/deploy-mcp@latest"
-    ]
+    "command": "deploy-mcp",
+    "args": []
   },
   "credentials": {
     "fields": [

package/content/integrations/erp.json

@@ -6,6 +6,7 @@
   "icon": "briefcase",
   "profile": "sales",
   "npmPackage": "@humanagencyp/erp-mcp",
+  "npmVersion": "0.3.3",
   "mcp": {
     "command": "erp-mcp",
     "args": []
@@ -138,86 +139,6 @@
       }
     }
   },
-  "templates": [
-    {
-      "name": "Draft quotes",
-      "description": "Look up items and customers, create and edit draft quotes. Nothing is sent to a customer or converted to an order.",
-      "risk": "low",
-      "mode": "automatic",
-      "bounds": {
-        "read_access": "unlimited",
-        "value_max": "5000",
-        "discount_max": "15",
-        "order_value_daily_max": "0",
-        "quote_daily_max": "20",
-        "send_daily_max": "0",
-        "order_daily_max": "0",
-        "setup_daily_max": "0"
-      },
-      "context": {
-        "currency": "EUR"
-      },
-      "intent": "Allow the agent to browse items and customers and prepare draft quotes for my review. It cannot send a quote to a customer or convert one into an order.",
-      "ttl": 2592000,
-      "tags": [
-        "drafts only",
-        "no sends",
-        "no orders"
-      ]
-    },
-    {
-      "name": "Send and confirm with review above limit",
-      "description": "Draft, send, and convert quotes into orders. Every send and every order requires your approval.",
-      "risk": "high",
-      "mode": "review",
-      "bounds": {
-        "read_access": "unlimited",
-        "value_max": "20000",
-        "discount_max": "20",
-        "order_value_daily_max": "50000",
-        "quote_daily_max": "50",
-        "send_daily_max": "20",
-        "order_daily_max": "10",
-        "setup_daily_max": "0"
-      },
-      "context": {
-        "currency": "EUR"
-      },
-      "intent": "Allow the agent to draft, send, and convert quotes into orders. Every quote sent to a customer and every order requires my review before it happens.",
-      "ttl": 2592000,
-      "tags": [
-        "20k EUR/document",
-        "review mode",
-        "10 orders/day"
-      ]
-    },
-    {
-      "name": "Load test data (with approval)",
-      "description": "Load a simulation package (customers and products) into the simulated ERP, for setting up a three-week test. No quoting, sending, or ordering — this template grants nothing but the one-time test-data load, and it still requires your approval.",
-      "risk": "high",
-      "mode": "review",
-      "bounds": {
-        "read_access": "none",
-        "value_max": "0",
-        "discount_max": "0",
-        "order_value_daily_max": "0",
-        "quote_daily_max": "0",
-        "send_daily_max": "0",
-        "order_daily_max": "0",
-        "setup_daily_max": "1"
-      },
-      "context": {
-        "currency": "EUR"
-      },
-      "intent": "Allow the agent to load one simulation package of test data into the simulated ERP, for my review before it happens. No other ERP action is granted by this mandate — set up test data separately from the mandate the agent uses for its actual work.",
-      "ttl": 2592000,
-      "tags": [
-        "setup only",
-        "review mode",
-        "1 load"
-      ]
-    }
-  ],
   "setupHint": "No configuration needed — works out of the box.",
   "setupGuide": [
     {

package/content/integrations/gmail.json

@@ -6,6 +6,7 @@
   "icon": "mail",
   "profile": "email",
   "npmPackage": "@shinzolabs/gmail-mcp",
+  "npmVersion": "1.7.4",
   "readPolicy": {
     "defaultAgeDays": 30
   },

package/content/integrations/linkedin.json

@@ -6,6 +6,7 @@
   "icon": "share",
   "profile": "publish",
   "npmPackage": "@humanagencyp/linkedin-mcp",
+  "npmVersion": "1.0.7",
   "mcp": {
     "command": "linkedin-mcp",
     "args": []

package/content/integrations/mail.json

@@ -6,6 +6,7 @@
   "icon": "mail",
   "profile": "email",
   "npmPackage": "@humanagencyp/email-mcp",
+  "npmVersion": "0.1.3",
   "mcp": {
     "command": "email-mcp",
     "args": []
@@ -86,54 +87,6 @@
       }
     }
   },
-  "templates": [
-    {
-      "name": "Work the inbox",
-      "description": "Read the simulated inbox and send replies. Cannot load or replace test data.",
-      "risk": "low",
-      "mode": "automatic",
-      "bounds": {
-        "read_access": "unlimited",
-        "recipient_max": "1",
-        "send_daily_max": "50",
-        "setup_daily_max": "0"
-      },
-      "context": {
-        "allowed_recipients": "",
-        "allowed_domains": ""
-      },
-      "intent": "Allow the agent to read the simulated inbox and reply to messages on its own. It cannot load or replace the test data the inbox was seeded with.",
-      "ttl": 2592000,
-      "tags": [
-        "read + reply",
-        "automatic",
-        "no setup"
-      ]
-    },
-    {
-      "name": "Load test data (with approval)",
-      "description": "Load a simulation package into an empty inbox. No reading or sending — a separate, one-time setup mandate.",
-      "risk": "high",
-      "mode": "review",
-      "bounds": {
-        "read_access": "none",
-        "recipient_max": "0",
-        "send_daily_max": "0",
-        "setup_daily_max": "1"
-      },
-      "context": {
-        "allowed_recipients": "",
-        "allowed_domains": ""
-      },
-      "intent": "Allow the agent to load one simulation package into an empty inbox, with my review before it happens. No reading or sending under this mandate — grant it separately from the mandate the agent uses for its daily work.",
-      "ttl": 2592000,
-      "tags": [
-        "setup only",
-        "review mode",
-        "1 load/day"
-      ]
-    }
-  ],
   "setupHint": "No configuration needed — works out of the box, in simulation mode.",
   "setupGuide": [
     {

package/content/integrations/mollie.json

@@ -6,6 +6,7 @@
   "icon": "card",
   "profile": "charge",
   "npmPackage": "mcp-remote",
+  "npmVersion": "0.14.3",
   "mcp": {
     "command": "mcp-remote",
     "args": [

package/content/integrations/records.json

@@ -6,6 +6,7 @@
   "icon": "file-text",
   "profile": "records",
   "npmPackage": "@humanagencyp/records-mcp",
+  "npmVersion": "1.0.4",
   "personalDefault": true,
   "mcp": {
     "command": "records-mcp",

package/dist/mcp-server/http.mjs

@@ -2607,6 +2607,20 @@ import { randomUUID } from "crypto";
 // src/lib/manifest-loader.ts
 import { readFileSync as readFileSync12, existsSync as existsSync11 } from "fs";
 import { join as join11, resolve } from "path";
+var EXACT_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function isExactSemver(value) {
+  return typeof value === "string" && EXACT_SEMVER_RE.test(value);
+}
+function invalidNpmPinReason(manifest) {
+  if (!manifest.npmPackage) return null;
+  if (manifest.npmVersion === void 0) {
+    return `npmPackage "${manifest.npmPackage}" is set but npmVersion is missing \u2014 every connector manifest must pin an exact tested version`;
+  }
+  if (!isExactSemver(manifest.npmVersion)) {
+    return `npmVersion ${JSON.stringify(manifest.npmVersion)} for "${manifest.npmPackage}" is not an exact semver (e.g. "1.2.3") \u2014 ranges, dist-tags like "latest", git specs, URLs, and file paths are not allowed`;
+  }
+  return null;
+}
 var manifests = /* @__PURE__ */ new Map();
 function loadManifests(integrationsDir) {
   const dir = resolve(
@@ -2629,6 +2643,11 @@ function loadManifests(integrationsDir) {
     const manifestPath = join11(dir, relativePath);
     try {
       const manifest = JSON.parse(readFileSync12(manifestPath, "utf-8"));
+      const pinReason = invalidNpmPinReason(manifest);
+      if (pinReason) {
+        console.error(`[ManifestLoader] Refusing manifest ${id} (${manifestPath}): ${pinReason}`);
+        continue;
+      }
       manifests.set(id, manifest);
       loaded++;
     } catch (err) {
@@ -4383,6 +4402,17 @@ var IntegrationManager = class {
   }
   running = /* @__PURE__ */ new Map();
   onToolsChanged = null;
+  /**
+   * Called when a persisted config was migrated to the manifest's command/args
+   * (see `migrateNpxConfig`) so the caller can write the fix back to
+   * `integrations.json` — the manager itself has no registry/persistence
+   * handle, by design (mirrors `onToolsChanged`). Without a subscriber the
+   * migration still takes effect for THIS start (the in-memory config is
+   * still corrected before spawn); only the one-time persistence is skipped,
+   * so every later start keeps re-migrating in memory, which is safe, if
+   * redundant.
+   */
+  onConfigMigrated = null;
   /**
    * Per-integration operation queue. Start/stop for one id are serialized
    * through here; without it, a second start issued while the first is still
@@ -4408,6 +4438,16 @@ var IntegrationManager = class {
   setOnToolsChanged(cb) {
     this.onToolsChanged = cb;
   }
+  /**
+   * Register a callback invoked when a persisted config is migrated off a
+   * stale `npx` command to the current manifest's command/args (see
+   * `migrateNpxConfig`). The caller is expected to persist `updates` against
+   * `id` in `integrations.json` so the fix survives the next boot instead of
+   * silently reapplying on every start.
+   */
+  setOnConfigMigrated(cb) {
+    this.onConfigMigrated = cb;
+  }
   /**
    * Is `npmPackage` present AND usable?
    *
@@ -4438,6 +4478,23 @@ var IntegrationManager = class {
       return false;
     }
   }
+  /**
+   * The installed version of `npmPackage`, or null if it isn't usably
+   * installed at all (see `isUsableInstall`) or its package.json has no
+   * parseable `version`. Never throws — an unreadable version is treated the
+   * same as "not installed", which is the safe direction: it drives a
+   * (re)install rather than a false "already pinned".
+   */
+  readInstalledVersion(npmPackage) {
+    if (!this.isUsableInstall(npmPackage)) return null;
+    const pkgJson = join13(INTEGRATIONS_DIR, "node_modules", ...npmPackage.split("/"), "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync14(pkgJson, "utf8"));
+      return typeof pkg.version === "string" ? pkg.version : null;
+    } catch {
+      return null;
+    }
+  }
   /**
    * Does the node_modules/.bin shim for `binName` exist? On Windows npm writes
    * `<name>`, `<name>.cmd`, and `<name>.ps1`; the .cmd variant is what actually
@@ -4448,9 +4505,32 @@ var IntegrationManager = class {
     const candidates = process.platform === "win32" ? [binName, `${binName}.cmd`, `${binName}.CMD`, `${binName}.ps1`] : [binName];
     return candidates.some((c) => existsSync13(join13(INTEGRATIONS_BIN, c)));
   }
+  /**
+   * The exact version THIS gateway's CURRENTLY LOADED manifest pins
+   * `config.npmPackage` to — or undefined when there's no npmPackage, no
+   * manifest for this id, or the manifest's `npmPackage` no longer names the
+   * same package as `config` (a manually re-pointed integration: nothing in
+   * the manifest vouches for a version of config's actual package).
+   *
+   * Read fresh from `getManifest(config.id)` on every call, never from
+   * anything persisted on `config` itself — manifests are reloaded fresh on
+   * every boot, `integrations.json` is not, so this is what keeps the pin
+   * from going stale the day after an integration was first activated. Used
+   * both to decide the npm install/update (`ensureInstalled`) and to decide
+   * whether a persisted `npx …` command must be refused/migrated
+   * (`migrateNpxConfig`) — one definition of "pinned", so the two can't
+   * disagree about which connectors it applies to.
+   */
+  pinnedVersionFor(config) {
+    if (!config.npmPackage) return void 0;
+    const manifest = getManifest(config.id);
+    return manifest?.npmPackage === config.npmPackage ? manifest.npmVersion : void 0;
+  }
   /**
    * Install an npm package into the managed integrations directory if not
-   * already present. Called automatically before spawning when
+   * already present, and — when `config`'s manifest pins an exact
+   * `npmVersion` for this same package — bring the installed copy to EXACTLY
+   * that version, older or newer. Called automatically before spawning when
    * config.npmPackage is set.
    *
    * Asynchronous ON PURPOSE. This used to be execSync, which blocked the MCP
@@ -4460,19 +4540,49 @@ var IntegrationManager = class {
    * CI runners: ~3.6s (Linux), ~5.4s (macOS), ~14s (Windows), and far worse
    * on machines with real-time antivirus.
    */
-  async ensureInstalled(npmPackage) {
+  async ensureInstalled(config) {
+    const npmPackage = config.npmPackage;
+    if (!npmPackage) return;
     ensureIntegrationsDir();
+    const pinnedVersion = this.pinnedVersionFor(config);
+    if (pinnedVersion) {
+      if (this.readInstalledVersion(npmPackage) === pinnedVersion) return;
+      return withInstallLock(async () => {
+        const current = this.readInstalledVersion(npmPackage);
+        if (current === pinnedVersion) return;
+        console.error(
+          `[IntegrationManager] ${npmPackage} ${current ?? "(not installed)"} \u2192 ${pinnedVersion} (pinned by manifest)`
+        );
+        const cleanFirst = !this.isUsableInstall(npmPackage);
+        await this.installNow(npmPackage, pinnedVersion, cleanFirst);
+      });
+    }
     if (this.isUsableInstall(npmPackage)) return;
     return withInstallLock(async () => {
       if (this.isUsableInstall(npmPackage)) return;
       await this.installNow(npmPackage);
     });
   }
-  /** The actual install. Callers MUST hold the install lock. */
-  async installNow(npmPackage) {
+  /**
+   * The actual install. Callers MUST hold the install lock.
+   *
+   * `exactVersion`, when given, is a pin already validated as an exact semver
+   * by the manifest loader (`isExactSemver`) — re-validated here anyway
+   * because this method does not trust its caller's caller, and because the
+   * version reaches a shell on Windows (see the package-name check below).
+   *
+   * `cleanFirst` (default true, i.e. today's behaviour for every caller
+   * except a version-only pin correction): wipe any existing package
+   * directory before installing. Needed for a genuinely broken/partial
+   * install, where stale files can make the reinstall itself fail; skipped
+   * for a USABLE install being corrected to a different pinned version, so a
+   * failed update leaves the previously-working version on disk instead of
+   * nothing at all.
+   */
+  async installNow(npmPackage, exactVersion, cleanFirst = true) {
     const pkgDir = join13(INTEGRATIONS_DIR, "node_modules", ...npmPackage.split("/"));
-    if (existsSync13(pkgDir)) {
-      console.error(`[IntegrationManager] Removing unusable install of ${npmPackage}`);
+    if (cleanFirst && existsSync13(pkgDir)) {
+      console.error(`[IntegrationManager] Removing ${exactVersion ? "outdated" : "unusable"} install of ${npmPackage}`);
       try {
         rmSync(pkgDir, { recursive: true, force: true });
       } catch (err) {
@@ -4482,18 +4592,22 @@ var IntegrationManager = class {
     if (!/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(npmPackage)) {
       throw new Error(`Refusing to install unsafe package name: ${JSON.stringify(npmPackage)}`);
     }
-    console.error(`[IntegrationManager] Installing ${npmPackage}...`);
+    if (exactVersion !== void 0 && !isExactSemver(exactVersion)) {
+      throw new Error(`Refusing to install ${npmPackage} at unsafe/non-exact version spec: ${JSON.stringify(exactVersion)}`);
+    }
+    const spec = exactVersion ? `${npmPackage}@${exactVersion}` : npmPackage;
+    console.error(`[IntegrationManager] Installing ${spec}...`);
     const startedAt = Date.now();
     const isWin = process.platform === "win32";
     await new Promise((resolve3, reject) => {
       const child = execFile(
         "npm",
-        ["install", "--no-fund", "--no-audit", npmPackage],
+        ["install", "--no-fund", "--no-audit", spec],
         {
           cwd: INTEGRATIONS_DIR,
           // Windows: a shell so cmd.exe finds npm.cmd (see EINVAL note above).
           // POSIX: no shell — npm is a normal executable and keeping shell off
-          // means the validated package name is still passed as a bare argv.
+          // means the validated package spec is still passed as a bare argv.
           shell: isWin,
           // No timeout: a slow install on a machine with antivirus is not an
           // error, and killing it midway is what created broken installs in
@@ -4503,20 +4617,28 @@ var IntegrationManager = class {
         },
         (err, _stdout, stderr) => {
           if (err) {
-            reject(new Error(`Failed to install ${npmPackage}: ${err.message}${stderr ? ` \u2014 ${stderr.trim()}` : ""}`));
+            reject(new Error(`Failed to install ${spec}: ${err.message}${stderr ? ` \u2014 ${stderr.trim()}` : ""}`));
             return;
           }
           resolve3();
         }
       );
-      child.on("error", (err) => reject(new Error(`Failed to run npm for ${npmPackage}: ${err.message}`)));
+      child.on("error", (err) => reject(new Error(`Failed to run npm for ${spec}: ${err.message}`)));
     });
     if (!this.isUsableInstall(npmPackage)) {
       throw new Error(
-        `Installed ${npmPackage} but it is not usable \u2014 package.json or its bin target is missing. Check ${INTEGRATIONS_DIR} for a partial install.`
+        `Installed ${spec} but it is not usable \u2014 package.json or its bin target is missing. Check ${INTEGRATIONS_DIR} for a partial install.`
       );
     }
-    console.error(`[IntegrationManager] Installed ${npmPackage} (${((Date.now() - startedAt) / 1e3).toFixed(1)}s)`);
+    if (exactVersion !== void 0) {
+      const installed = this.readInstalledVersion(npmPackage);
+      if (installed !== exactVersion) {
+        throw new Error(
+          `Installed ${npmPackage} but got version ${installed ?? "unknown"}, expected the pinned ${exactVersion}.`
+        );
+      }
+    }
+    console.error(`[IntegrationManager] Installed ${spec} (${((Date.now() - startedAt) / 1e3).toFixed(1)}s)`);
   }
   /**
    * Connect a client to its transport, but never wait indefinitely. Resolves
@@ -4575,7 +4697,26 @@ var IntegrationManager = class {
       throw new Error(`${config.id}: ${SIMULATION_BLOCK_REASON}`);
     }
     if (config.npmPackage) {
-      await this.ensureInstalled(config.npmPackage);
+      await this.ensureInstalled(config);
+    }
+    const pinnedVersion = this.pinnedVersionFor(config);
+    if (pinnedVersion && config.command === "npx") {
+      const manifest = getManifest(config.id);
+      const migrated = {
+        command: manifest.mcp.command,
+        args: manifest.mcp.args,
+        env: manifest.mcp.env ?? config.env
+      };
+      console.error(
+        `[IntegrationManager] ${config.id}: command migrated to manifest (was npx ${config.args.join(" ")})`
+      );
+      config = { ...config, ...migrated };
+      this.onConfigMigrated?.(config.id, migrated);
+    }
+    if (pinnedVersion && config.command === "npx") {
+      throw new Error(
+        `${config.id}: refusing to spawn a pinned connector ("${config.npmPackage}"@${pinnedVersion}) via npx \u2014 this would ignore the pinned local install and fetch the package fresh on every start. The manifest's mcp.command must name the installed binary, not "npx".`
+      );
     }
     const env = this.resolveEnvKeys(config);
     if (isSimulationMode()) {
@@ -5129,6 +5270,10 @@ function refreshAllSessions() {
 integrationManager.setOnToolsChanged(() => {
   refreshAllSessions();
 });
+integrationManager.setOnConfigMigrated((id, updates) => {
+  integrationRegistry.update(id, updates);
+  console.error(`[Suveren MCP] ${id}: persisted config migrated (${Object.keys(updates).join(", ")})`);
+});
 var app = express();
 app.use(express.json());
 app.use((_req, res, next) => {

package/lib/node-version.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Types for the plain-ESM Node version check (see config.d.mts for why the
+ * .mjs modules ship declarations).
+ */
+
+export declare const MIN_NODE_MAJOR: number;
+export declare function unsupportedNodeReason(version: string): string | null;

package/lib/node-version.mjs

@@ -0,0 +1,28 @@
+/**
+ * Minimum Node.js version for the gateway — checked at start by
+ * bundle/bin/suveren-gateway.js and bundle/server.js.
+ *
+ * The connectors the gateway installs (crm, erp, email, records — all built on
+ * better-sqlite3 13) need Node 22. `engines` in package.json is not enough:
+ * npm only WARNS on a mismatch, and for an unpinned install it silently picks
+ * an older connector that still runs on the old Node. With pinned connector
+ * versions the pinned connector is installed anyway and crashes on its first
+ * database call. Refusing at start, with the reason, is the only visible
+ * failure. Keep MIN_NODE_MAJOR in step with `engines` in package.json.tpl.
+ */
+
+export const MIN_NODE_MAJOR = 22;
+
+/**
+ * Returns null when `version` (e.g. process.versions.node, "22.11.0") is
+ * supported, otherwise a message naming both versions. An unparseable version
+ * is refused — the safe direction.
+ */
+export function unsupportedNodeReason(version) {
+  const major = Number.parseInt(String(version).split('.')[0], 10);
+  if (Number.isInteger(major) && major >= MIN_NODE_MAJOR) return null;
+  return (
+    `Suveren gateway needs Node.js ${MIN_NODE_MAJOR} or newer — this is Node.js ${version}. ` +
+    `Install a current Node.js (https://nodejs.org) and start the gateway again.`
+  );
+}