@suveren/gateway 0.9.0 → 0.10.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+](https://nodejs.org/).
+Requires [Node.js 20.18.1+](https://nodejs.org/).
 
 ```bash
 npm install -g @suveren/gateway
@@ -153,6 +153,38 @@ See [`docs/development.md`](docs/development.md) for environment variables, test
 
 ---
 
+## Pinning the Authority Server's TLS certificate
+
+Opt-in, for self-hosted Authority Servers with a stable signing key — not needed against the hosted `suveren.ai`, and off by default.
+
+The gateway already verifies the Authority Server can *sign* under the right key before it ever sends an API key or session cookie. What that alone does not cover: something sitting on the network path between the gateway and the Authority Server, presenting its own TLS certificate, that a locally-trusted CA (e.g. a custom `--ca-file`) would otherwise accept. TLS certificate pinning closes that gap by pinning the Authority Server's certificate public key (SPKI, SHA-256) — every connection after that must present the same key, or the gateway refuses it and locks.
+
+**Pinning only protects from the moment the fingerprint has actually been checked over a second channel** — a phone call, a video call, a separate trusted connection. That is why enabling it requires `--expect-fingerprint`: not an optional confirmation step, but the check itself. Recommended: enable it once, right after pairing, from a network you already trust.
+
+```bash
+# Get the Authority Server's own fingerprint independently — ask the operator,
+# or run this yourself on a trusted network:
+openssl s_client -connect your-as-host:443 </dev/null 2>/dev/null \
+  | openssl x509 -pubkey -noout \
+  | openssl pkey -pubin -outform der \
+  | openssl dgst -sha256
+
+# Compare it against what you were told out-of-band, THEN enable:
+suveren-gateway config set pin-tls on --expect-fingerprint <the-sha256-you-just-confirmed>
+suveren-gateway restart
+```
+
+A few things worth knowing before turning it on:
+
+- **Certificate renewal with the SAME key keeps the pin working** — nothing to do. Renew with the same key where your tooling supports it (e.g. `certbot renew --reuse-key`).
+- **A renewal under a NEW key locks the gateway** (`as-tls-mismatch`) until an operator re-pairs — this is deliberate fail-closed behavior, not a bug. Re-pairing means clearing `<dataDir>/as-pairing.json` and signing in again.
+- Pinned connections trust Node's own bundled root certificates plus `--ca-file` / `NODE_EXTRA_CA_CERTS` — **not** your operating system's trust store.
+- `suveren-gateway config set pin-tls off` disables enforcement at any time; the stored fingerprint stays on file, so turning it back on later with the SAME `--expect-fingerprint` value succeeds immediately (it is still required every time — stating it again is cheap, and the command refuses outright if it doesn't match what's on file).
+
+See `suveren-gateway config help` for the full command reference.
+
+---
+
 ## Technical Documentation
 
 | Document | Contents |

package/bin/suveren-gateway.js

@@ -17,7 +17,8 @@ import { homedir, platform, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildLaunchAgentPlist, buildMacLauncher, buildSystemdUnit, buildWindowsTaskXml } from '../lib/autostart-templates.mjs';
-import { DEFAULT_AS_URL, readConfig, writeConfig, validateAsUrl, validateCaFile, resolveAsUrl } from '../lib/config.mjs';
+import { DEFAULT_AS_URL, readConfig, writeConfig, validateAsUrl, validateCaFile, validatePinTls, resolveAsUrl, resolvePinTls, resolvePinTlsExpectedFingerprint } from '../lib/config.mjs';
+import { readPairing as readAsPairing, recordTlsPin, formatFingerprint, normalizeFingerprint } from '../lib/as-pairing.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -61,6 +62,101 @@ function flagValue(args, name) {
   return args[i + 1];
 }
 
+/**
+ * The TLS SPKI fingerprint currently on file for `asUrl`, if any — either a
+ * real, verified pin (as-pairing.json, captured at a past sign-in) or a
+ * staged-but-not-yet-verified one (config.json's `pinTlsExpectedFingerprint`
+ * — set by a PRIOR `--expect-fingerprint` run before any pairing existed).
+ * The pairing value always wins when both are present.
+ */
+function currentTlsFingerprintHex(dataDir, asUrl) {
+  const pairing = readAsPairing(dataDir);
+  if (pairing && pairing.asUrl === asUrl && pairing.tlsSpkiPinHex) return pairing.tlsSpkiPinHex;
+  return resolvePinTlsExpectedFingerprint(dataDir);
+}
+
+function printFingerprintHowTo(asUrl) {
+  let host = asUrl;
+  try { host = new URL(asUrl).host; } catch { /* keep the raw string */ }
+  console.error(`Obtain the Authority Server's OWN fingerprint independently — e.g. ask the operator over`);
+  console.error(`the phone, or run this yourself on a network you already trust:`);
+  console.error(``);
+  console.error(`  openssl s_client -connect ${host} </dev/null 2>/dev/null \\`);
+  console.error(`    | openssl x509 -pubkey -noout \\`);
+  console.error(`    | openssl pkey -pubin -outform der \\`);
+  console.error(`    | openssl dgst -sha256`);
+  console.error(``);
+  console.error(`Compare it against the value shown above (if any) BEFORE re-running this with --expect-fingerprint.`);
+}
+
+/**
+ * Mandatory out-of-band check for enabling pin-tls (opt-in TLS certificate
+ * pinning) — shared by `start --pin-tls` and `config set pin-tls on`.
+ * Without this, turning pin-tls on would either silently trust whatever
+ * certificate the Authority Server happens to present at the next sign-in
+ * (defeating the whole point of pinning) or require a SEPARATE manual
+ * verification step a script could skip. `--expect-fingerprint` makes the
+ * operator state, on the command line, the value they already checked
+ * out-of-band — refusing outright when it's missing or doesn't match
+ * whatever is already on file.
+ *
+ * Returns the normalized (lowercase, no separators) hex fingerprint to
+ * commit, or exits the process (code 1) having already printed why.
+ */
+function requireConfirmedFingerprint(args, asUrl) {
+  const flag = flagValue(args, '--expect-fingerprint');
+  const existingHex = currentTlsFingerprintHex(DATA_DIR, asUrl);
+
+  if (!flag) {
+    console.error(`--expect-fingerprint is required to enable pin-tls — this is the Authority Server's TLS`);
+    console.error(`certificate public-key fingerprint (SHA-256 of the leaf SPKI), checked over a second`);
+    console.error(`channel BEFORE trusting it, not just whatever this gateway happens to see on the wire.`);
+    console.error(``);
+    if (existingHex) {
+      console.error(`Currently on file for ${asUrl}:`);
+      console.error(`  ${formatFingerprint(existingHex)}`);
+      console.error(``);
+    }
+    printFingerprintHowTo(asUrl);
+    process.exit(1);
+  }
+
+  const norm = normalizeFingerprint(flag);
+  if (!norm.ok) {
+    console.error(`Invalid --expect-fingerprint: ${norm.error}`);
+    process.exit(1);
+  }
+
+  if (existingHex && existingHex !== norm.hex) {
+    console.error(`--expect-fingerprint does not match the fingerprint already on file for ${asUrl}:`);
+    console.error(`  on file:  ${formatFingerprint(existingHex)}`);
+    console.error(`  provided: ${formatFingerprint(norm.hex)}`);
+    console.error(``);
+    console.error(`If the Authority Server's certificate changed INTENTIONALLY (a new key, not just a`);
+    console.error(`renewal), clear the pairing (${join(DATA_DIR, 'as-pairing.json')}) and sign in again to`);
+    console.error(`re-pin it, then re-run this command with the new fingerprint.`);
+    process.exit(1);
+  }
+
+  return norm.hex;
+}
+
+/**
+ * Commit a confirmed fingerprint: into the existing pairing record
+ * (as-pairing.json) when one exists for this URL, so it is enforced from
+ * the very next connection on — or, when no pairing exists yet (nothing to
+ * attach a TLS pin to), staged in config.json's `pinTlsExpectedFingerprint`
+ * for the control plane to enforce at the NEXT sign-in's challenge (see
+ * checkAsKeyBeforeLogin in apps/control-plane/src/routes/auth.ts), which
+ * moves it into as-pairing.json and clears the staging field once it
+ * verifies.
+ */
+function commitConfirmedFingerprint(dataDir, asUrl, hex) {
+  if (recordTlsPin(dataDir, asUrl, hex)) return 'pinned';
+  writeConfig(dataDir, { pinTlsExpectedFingerprint: hex });
+  return 'staged';
+}
+
 async function start(args) {
   const detach = args.includes('--detach') || args.includes('-d');
 
@@ -93,6 +189,27 @@ async function start(args) {
     caFileToSave = v.path;
   }
 
+  // --pin-tls: a boolean flag (turns TLS certificate pinning ON — there is
+  // no `start --pin-tls off`; use `config set pin-tls off` for that).
+  // Validated against the EFFECTIVE as-url for this very start (the flag
+  // above, if given, wins over whatever is saved) — enabling it for an
+  // http:// Authority Server has nothing to pin. Also requires
+  // --expect-fingerprint (the mandatory out-of-band check — see
+  // requireConfirmedFingerprint) before it can be turned on at all.
+  const pinTlsFlag = args.includes('--pin-tls');
+  let pinTlsToSave = null;
+  let confirmedFingerprintHex = null;
+  if (pinTlsFlag) {
+    const effectiveAsUrl = asUrlToSave ?? resolveAsUrl(DATA_DIR);
+    const v = validatePinTls(effectiveAsUrl);
+    if (!v.ok) {
+      console.error(`Invalid --pin-tls: ${v.error}`);
+      process.exit(1);
+    }
+    confirmedFingerprintHex = requireConfirmedFingerprint(args, effectiveAsUrl);
+    pinTlsToSave = true;
+  }
+
   if (await isAlreadyRunning()) {
     console.error(`suveren-gateway is already running (pid ${readPid()}). Use \`suveren-gateway stop\` first or \`suveren-gateway restart\`.`);
     process.exit(1);
@@ -141,6 +258,17 @@ async function start(args) {
     writeConfig(DATA_DIR, { caFile: caFileToSave });
     console.log(`CA file: ${caFileToSave} (saved — applied to every process this gateway starts)`);
   }
+  if (pinTlsToSave) {
+    const effectiveAsUrl = asUrlToSave ?? resolveAsUrl(DATA_DIR);
+    const committed = commitConfirmedFingerprint(DATA_DIR, effectiveAsUrl, confirmedFingerprintHex);
+    writeConfig(DATA_DIR, { pinTls: true });
+    console.log(`TLS pinning: ON (fingerprint ${formatFingerprint(confirmedFingerprintHex)} confirmed)`);
+    console.log(
+      committed === 'pinned'
+        ? `  Enforced from your next connection on.`
+        : `  Staged — the first sign-in's challenge must match it (refused otherwise); it then becomes the permanent pin.`,
+    );
+  }
 
   if (detach) {
     const out = openSync(LOG_FILE, 'a');
@@ -368,14 +496,46 @@ function printConfigHelp() {
   console.log(`suveren-gateway config — read or save gateway settings
 
 Usage:
-  suveren-gateway config get [as-url|ca-file]   Print the resolved value(s)
-  suveren-gateway config set as-url <url>       Save the Authority Server URL
-  suveren-gateway config set ca-file <path>     Save a CA bundle for internal TLS
+  suveren-gateway config get [as-url|ca-file|pin-tls]  Print the resolved value(s)
+  suveren-gateway config set as-url <url>              Save the Authority Server URL
+  suveren-gateway config set ca-file <path>            Save a CA bundle for internal TLS
+  suveren-gateway config set pin-tls on --expect-fingerprint <sha256-hex>
+                                                        Pin the Authority Server's TLS certificate
+  suveren-gateway config set pin-tls off               Stop enforcing the TLS certificate pin
 
 Saved in ${join(DATA_DIR, 'config.json')}.
 Precedence at start: --as-url flag > env SUVEREN_AS_URL > saved as-url >
 default (${DEFAULT_AS_URL}).
 
+pin-tls (default off, self-hosted Authority Servers with a stable signing
+key) requires https:// and pins the Authority Server's TLS certificate
+public key; every connection after it's established must present that same
+key, or the gateway refuses it and locks (reason: as-tls-mismatch) until an
+operator resolves it. It protects against a party on the network between
+this gateway and the Authority Server presenting its OWN certificate — but
+ONLY from the moment the fingerprint has actually been checked over a
+second channel (phone, a separate trusted connection), which is why
+--expect-fingerprint is mandatory: it is not optional confirmation, it IS
+the check. Recommended: enable it once, right after pairing, from a network
+you already trust.
+
+--expect-fingerprint <sha256-hex>  The Authority Server's own TLS leaf
+  certificate public-key fingerprint (SHA-256 of the SPKI — colons/spacing
+  accepted, case-insensitive), confirmed over a second channel BEFORE
+  running this command. Without it, this command refuses and prints how to
+  obtain the fingerprint yourself.
+  - If a pin is already on file and it DIFFERS, this refuses outright —
+    clear the pairing first if the certificate changed intentionally (a
+    NEW key; a renewal with the SAME key never needs this).
+  - If none is on file yet, the value is trusted immediately if a
+    signing-key pairing already exists, or staged for the very next
+    sign-in's challenge to match (refused otherwise) if it doesn't.
+
+Renewing the certificate under the SAME key (e.g. \`certbot renew
+--reuse-key\`) keeps the pin working with no action needed; a renewal under
+a NEW key locks the gateway until an operator re-pairs (clears
+<dataDir>/as-pairing.json and signs in again).
+
 Changes take effect on the next \`suveren-gateway start\` / \`restart\` — a
 running gateway keeps using what it already resolved at its own startup.
 `);
@@ -390,10 +550,12 @@ async function config(args) {
     if (!key) {
       console.log(`as-url:  ${resolveAsUrl(DATA_DIR)}`);
       console.log(`ca-file: ${saved.caFile ?? '(not set)'}`);
+      console.log(`pin-tls: ${resolvePinTls(DATA_DIR) ? 'on' : 'off'}`);
       return;
     }
     if (key === 'as-url') { console.log(resolveAsUrl(DATA_DIR)); return; }
     if (key === 'ca-file') { console.log(saved.caFile ?? ''); return; }
+    if (key === 'pin-tls') { console.log(resolvePinTls(DATA_DIR) ? 'on' : 'off'); return; }
     console.error(`Unknown config key: ${key}\n`);
     printConfigHelp();
     process.exit(2);
@@ -432,6 +594,37 @@ async function config(args) {
       console.log('Restart to pick it up: suveren-gateway restart');
       return;
     }
+    if (key === 'pin-tls') {
+      if (value !== 'on' && value !== 'off') {
+        console.error('Usage: suveren-gateway config set pin-tls on|off [--expect-fingerprint <sha256-hex>]');
+        process.exit(2);
+      }
+      if (value === 'off') {
+        writeConfig(DATA_DIR, { pinTls: false });
+        console.log('Saved pin-tls: off');
+        console.log('Restart to pick it up: suveren-gateway restart');
+        return;
+      }
+      // value === 'on': requires the out-of-band fingerprint check (see
+      // requireConfirmedFingerprint) — never trusts whatever the AS
+      // happens to present at the next sign-in without one.
+      const effectiveAsUrl = resolveAsUrl(DATA_DIR);
+      const v = validatePinTls(effectiveAsUrl);
+      if (!v.ok) {
+        console.error(`Invalid pin-tls: ${v.error}`);
+        process.exit(1);
+      }
+      const hex = requireConfirmedFingerprint(args, effectiveAsUrl);
+      const committed = commitConfirmedFingerprint(DATA_DIR, effectiveAsUrl, hex);
+      writeConfig(DATA_DIR, { pinTls: true });
+      console.log(`Saved pin-tls: on (fingerprint ${formatFingerprint(hex)} confirmed)`);
+      console.log(
+        committed === 'pinned'
+          ? 'Restart to pick it up: suveren-gateway restart'
+          : 'Restart and sign in again — the first challenge must match this fingerprint: suveren-gateway restart',
+      );
+      return;
+    }
     console.error(`Unknown config key: ${key}\n`);
     printConfigHelp();
     process.exit(2);
@@ -945,15 +1138,20 @@ Usage:
   suveren-gateway start [--detach]           Run the gateway (foreground by default)
     [--as-url <url>]                         Authority Server URL (saved for next time)
     [--ca-file <path>]                       Internal CA bundle (saved for next time)
+    [--pin-tls --expect-fingerprint <hex>]   Pin the AS TLS certificate (saved; https:// only — see below)
   suveren-gateway stop                       Stop a detached gateway
   suveren-gateway restart                    Stop, then start --detach
   suveren-gateway status                     Show running state + health
   suveren-gateway logs [--tail]               Print or tail ~/.suveren/gateway.log
   suveren-gateway service <cmd>               Run as a login service that survives reboot
                                               (install | uninstall | status)
-  suveren-gateway config get [as-url|ca-file] Print the resolved value(s)
+  suveren-gateway config get [as-url|ca-file|pin-tls]  Print the resolved value(s)
   suveren-gateway config set as-url <url>     Save the Authority Server URL
   suveren-gateway config set ca-file <path>   Save a CA bundle for internal TLS
+  suveren-gateway config set pin-tls on --expect-fingerprint <hex>
+                                              Pin the Authority Server's TLS certificate
+                                              (see \`suveren-gateway config help\` for the fingerprint check)
+  suveren-gateway config set pin-tls off      Stop enforcing the TLS certificate pin
   suveren-gateway help                        Print this help
 
 Environment:

package/content/integrations/erp.json

@@ -0,0 +1,184 @@
+{
+  "id": "erp",
+  "name": "ERP",
+  "version": "1.0.0",
+  "description": "Quote-to-order — items, customers, quotes, orders",
+  "icon": "briefcase",
+  "profile": "sales",
+  "npmPackage": "@humanagencyp/erp-mcp",
+  "mcp": {
+    "command": "erp-mcp",
+    "args": []
+  },
+  "credentials": {
+    "fields": [
+      {
+        "key": "databaseUrl",
+        "label": "Database URL (optional)",
+        "type": "text",
+        "placeholder": "Leave empty for local SQLite",
+        "optional": true
+      }
+    ],
+    "envMapping": {
+      "DATABASE_URL": "databaseUrl"
+    }
+  },
+  "personalDefault": true,
+  "oauth": null,
+  "toolGating": {
+    "default": {
+      "executionMapping": {},
+      "staticExecution": {}
+    },
+    "overrides": {
+      "list_items": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "get_item": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "find_customers": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "get_customer": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "list_quotes": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "get_quote": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "list_orders": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "get_order": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "create_quote": {
+        "executionMapping": {
+          "value": "value",
+          "discount_pct": "discount_pct",
+          "currency": "currency"
+        },
+        "staticExecution": {
+          "action_type": "quote"
+        },
+        "actionLabel": "Quote drafted"
+      },
+      "update_quote": {
+        "executionMapping": {
+          "value": "value",
+          "discount_pct": "discount_pct",
+          "currency": "currency"
+        },
+        "staticExecution": {
+          "action_type": "quote"
+        },
+        "actionLabel": "Quote updated"
+      },
+      "send_quote": {
+        "executionMapping": {
+          "value": "value",
+          "discount_pct": "discount_pct",
+          "currency": "currency"
+        },
+        "staticExecution": {
+          "action_type": "send"
+        },
+        "actionLabel": "Quote sent"
+      },
+      "convert_quote_to_order": {
+        "executionMapping": {
+          "value": "value",
+          "discount_pct": "discount_pct",
+          "currency": "currency"
+        },
+        "staticExecution": {
+          "action_type": "order"
+        },
+        "actionLabel": "Quote converted to order"
+      }
+    }
+  },
+  "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"
+      },
+      "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"
+      },
+      "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"
+      ]
+    }
+  ],
+  "setupHint": "No configuration needed — works out of the box.",
+  "setupGuide": [
+    {
+      "title": "Ready to use",
+      "description": "The ERP connector stores data locally on your machine, seeded with a small demo catalog and customer list. No external account or API key needed."
+    },
+    {
+      "title": "Optional: use a shared database",
+      "description": "For team use, provide a PostgreSQL connection string in the Database URL field. Otherwise, leave it empty to use local SQLite storage."
+    }
+  ]
+}

package/content/integrations/index.json

@@ -6,6 +6,7 @@
     "records": "records.json",
     "linkedin": "linkedin.json",
     "calendar": "calendar.json",
-    "deploy-github": "deploy-github.json"
+    "deploy-github": "deploy-github.json",
+    "erp": "erp.json"
   }
 }