@suveren/gateway 0.10.0 → 0.11.0

package/README.md

@@ -185,6 +185,42 @@ See `suveren-gateway config help` for the full command reference.
 
 ---
 
+## Simulation mode — block every real system
+
+A mandate is bound to a *profile* (e.g. "sales"), not to a specific connector. If a real
+connector (e.g. a live ERP account) and a simulated one (the built-in ERP/CRM/email
+simulators) share a profile on one gateway, a mandate meant only for testing also
+authorizes the real connector — nothing about the mandate says which one it's for.
+
+Simulation mode closes that gap gateway-wide: turn it on and **every connector without a
+manifest `simulation` marker is refused to even start** (the built-in ERP, CRM, and email
+simulators all declare one; a connected Gmail or live ERP account does not), and every
+connector that does declare one has its mode forced to `simulation`, overriding whatever
+credential value is on file. Mandates and profiles are completely unaffected, and the
+Authority Server never learns this is on — it's a purely local, gateway-side switch.
+
+```bash
+# Start fresh with real systems blocked:
+suveren-gateway start --simulation
+
+# Or flip it on an existing install (takes effect on the next start/restart):
+suveren-gateway simulation on
+suveren-gateway restart
+
+# Check the mode (the SAVED setting and, if the gateway is running, the LIVE one):
+suveren-gateway simulation status
+
+# Turning it off makes real systems reachable again, so it requires typed
+# confirmation (or --confirm live for scripts) — turning it ON does not:
+suveren-gateway simulation off
+suveren-gateway restart
+```
+
+`suveren-gateway status` also shows the current mode. See `suveren-gateway simulation 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, validatePinTls, resolveAsUrl, resolvePinTls, resolvePinTlsExpectedFingerprint } from '../lib/config.mjs';
+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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -210,6 +211,13 @@ async function start(args) {
     pinTlsToSave = true;
   }
 
+  // --simulation: the safe direction (turning OFF real systems), so — unlike
+  // `simulation off` — this needs no confirmation. Only ever turns it ON;
+  // there is no `start --no-simulation` (use `simulation off` for that, which
+  // DOES require confirmation, since that direction makes real systems
+  // reachable again).
+  const simulationFlag = args.includes('--simulation');
+
   if (await isAlreadyRunning()) {
     console.error(`suveren-gateway is already running (pid ${readPid()}). Use \`suveren-gateway stop\` first or \`suveren-gateway restart\`.`);
     process.exit(1);
@@ -269,6 +277,10 @@ async function start(args) {
         : `  Staged — the first sign-in's challenge must match it (refused otherwise); it then becomes the permanent pin.`,
     );
   }
+  if (simulationFlag) {
+    writeConfig(DATA_DIR, { simulation: true });
+    console.log(`Simulation mode: ON (saved) — every connector without a manifest "simulation" marker will be blocked.`);
+  }
 
   if (detach) {
     const out = openSync(LOG_FILE, 'a');
@@ -414,6 +426,7 @@ async function status() {
         console.log('suveren-gateway: running (managed by the login service)');
         console.log(`  UI:           http://localhost:${SUVEREN_PORT}`);
         console.log(`  Vault:        ${body.vaultUnlocked ? 'unlocked' : 'locked'}`);
+        console.log(`  Simulation:   ${body.simulation ? 'on — real systems are blocked' : 'off'}`);
         console.log(`  Version:      ${body.version ?? 'unknown'} (running)`);
         console.log(`  Service:      suveren-gateway service status`);
         return;
@@ -438,6 +451,7 @@ async function status() {
     console.log(`suveren-gateway: running (pid ${pid})`);
     console.log(`  UI:           http://localhost:${SUVEREN_PORT}`);
     console.log(`  Vault:        ${body.vaultUnlocked ? 'unlocked' : 'locked'}`);
+    console.log(`  Simulation:   ${body.simulation ? 'on — real systems are blocked' : 'off'}`);
     console.log(`  Version:      ${body.version ?? 'unknown'} (running)`);
     if (CLI_VERSION) console.log(`                ${CLI_VERSION} (installed CLI)`);
     if (CLI_VERSION && body.version && body.version !== CLI_VERSION && body.version !== 'dev') {
@@ -634,6 +648,102 @@ async function config(args) {
   if (sub !== undefined && sub !== 'help' && sub !== '--help' && sub !== '-h') process.exit(2);
 }
 
+// ─── simulation: gateway-wide switch that blocks every real system ──────
+//
+// A mandate is bound to a PROFILE, not a connector — see suveren-gateway's
+// tool-proxy.ts (`profileMatches`). Put a real connector and a simulated one
+// on the same profile, and one mandate authorizes both. Simulation mode
+// closes that generically: ON blocks every connector whose manifest carries
+// no `simulation` marker, and forces every connector that DOES have one into
+// its simulated mode, regardless of what credential value is on file.
+// Mandates and profiles are unaffected; the Authority Server never learns
+// about this — it is a purely local, gateway-side switch. See
+// apps/mcp-server/src/lib/simulation-mode.ts for enforcement.
+
+function printSimulationHelp() {
+  console.log(`suveren-gateway simulation — gateway-wide switch that blocks every real system
+
+Usage:
+  suveren-gateway simulation on               Block every real connector (no confirmation — the safe direction)
+  suveren-gateway simulation off              Make real systems reachable again (requires confirmation)
+    [--confirm live]                          Non-interactive confirmation
+  suveren-gateway simulation status           Show the saved setting and (if running) the live one
+
+Changes take effect on the next \`suveren-gateway start\` / \`restart\`.
+`);
+}
+
+async function printSimulationStatus() {
+  const saved = resolveSimulation(DATA_DIR);
+  console.log(`Saved:   ${saved ? 'on' : 'off'}`);
+  try {
+    const res = await fetch(`http://localhost:${SUVEREN_PORT}/health`, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const body = await res.json();
+      const running = body.simulation === true;
+      console.log(`Running: ${running ? 'on' : 'off'}${running !== saved ? '  (restart to apply the saved value)' : ''}`);
+    }
+  } catch {
+    // Not reachable — the saved value is all there is to report.
+  }
+}
+
+/** Read one line from stdin, or undefined if there is no TTY to prompt on
+ *  (so a non-interactive caller gets a clean abort instead of a hang). */
+async function promptLine(question) {
+  if (!process.stdin.isTTY) return undefined;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function simulation(args) {
+  const sub = args[0] ?? 'status';
+
+  if (sub === 'help' || sub === '--help' || sub === '-h') { printSimulationHelp(); return; }
+
+  if (sub === 'status') {
+    await printSimulationStatus();
+    return;
+  }
+
+  if (sub === 'on') {
+    // The safe direction — blocking real systems needs no confirmation.
+    writeConfig(DATA_DIR, { simulation: true });
+    console.log('Simulation mode: ON (saved) — every connector without a manifest "simulation" marker will be blocked.');
+    console.log('Restart to pick it up: suveren-gateway restart');
+    return;
+  }
+
+  if (sub === 'off') {
+    console.error('Turning simulation mode OFF makes every real system reachable again: any connector');
+    console.error('without a manifest "simulation" marker (e.g. a live Gmail or ERP account) will spawn');
+    console.error('and execute for real the next time this gateway starts.');
+    console.error('');
+    let typed = flagValue(args, '--confirm');
+    if (typed === undefined) {
+      typed = await promptLine('Type "live" to confirm, or anything else to abort: ');
+    }
+    if (typed !== 'live') {
+      console.error(typed === undefined
+        ? 'No TTY to confirm on and no --confirm given — aborted. Simulation mode unchanged.'
+        : 'Aborted — simulation mode unchanged.');
+      process.exit(1);
+    }
+    writeConfig(DATA_DIR, { simulation: false });
+    console.log('Simulation mode: OFF (saved) — real systems become reachable on next restart.');
+    console.log('Restart to pick it up: suveren-gateway restart');
+    return;
+  }
+
+  console.error(`Unknown: simulation ${sub}\n`);
+  printSimulationHelp();
+  process.exit(2);
+}
+
 // ─── service: install autostart-on-login (survives reboot) ──────────────
 //
 // Keeps the gateway PROCESS always running (starts on login, restarts on
@@ -1139,9 +1249,10 @@ Usage:
     [--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)
+    [--simulation]                           Block every real system (saved — see \`simulation help\`)
   suveren-gateway stop                       Stop a detached gateway
   suveren-gateway restart                    Stop, then start --detach
-  suveren-gateway status                     Show running state + health
+  suveren-gateway status                     Show running state + health (incl. simulation mode)
   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)
@@ -1152,6 +1263,8 @@ Usage:
                                               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 simulation on|off|status    Block (or unblock) every real system
+                                              (see \`suveren-gateway simulation help\`)
   suveren-gateway help                        Print this help
 
 Environment:
@@ -1159,6 +1272,7 @@ Environment:
   SUVEREN_MCP_PORT    MCP server port (default 3430)
   SUVEREN_DATA_DIR    Data directory (default ~/.suveren)
   SUVEREN_AS_URL      Authority Server URL — overrides the saved as-url
+  SUVEREN_SIMULATION  1 to force simulation mode for this run — overrides the saved setting
 
 Authority Server resolution order: --as-url flag > SUVEREN_AS_URL env >
 saved as-url (\`config set as-url\`) > default (${DEFAULT_AS_URL}).
@@ -1181,6 +1295,7 @@ async function main() {
     case 'logs':    await logs(argv.slice(1)); break;
     case 'service': await service(argv.slice(1)); break;
     case 'config':  await config(argv.slice(1)); break;
+    case 'simulation': await simulation(argv.slice(1)); break;
     case 'help':
     case '--help':
     case '-h':

package/content/integrations/crm.json

@@ -18,12 +18,24 @@
         "type": "text",
         "placeholder": "Leave empty for local SQLite",
         "optional": true
+      },
+      {
+        "key": "mode",
+        "label": "Mode (optional)",
+        "type": "text",
+        "placeholder": "simulation (default) — live needs an adapter for your CRM",
+        "optional": true
       }
     ],
     "envMapping": {
-      "DATABASE_URL": "databaseUrl"
+      "DATABASE_URL": "databaseUrl",
+      "CRM_MODE": "mode"
     }
   },
+  "simulation": {
+    "field": "mode",
+    "default": "simulation"
+  },
   "personalDefault": true,
   "oauth": null,
   "toolGating": {
@@ -118,6 +130,15 @@
         "category": "read",
         "boundField": "export_access",
         "requiredValue": "allowed"
+      },
+      "load_simulation": {
+        "executionMapping": {},
+        "staticExecution": {
+          "contact_type": "customer",
+          "action_type": "setup"
+        },
+        "actionLabel": "Test data loaded",
+        "hideUnlessAuthorized": true
       }
     }
   },
@@ -130,7 +151,8 @@
       "bounds": {
         "read_access": "unlimited",
         "write_daily_max": "50",
-        "delete_daily_max": "0"
+        "delete_daily_max": "0",
+        "setup_daily_max": "0"
       },
       "context": {
         "contact_type": "customer,lead,partner,vendor"
@@ -150,7 +172,8 @@
       "bounds": {
         "read_access": "unlimited",
         "write_daily_max": "50",
-        "delete_daily_max": "10"
+        "delete_daily_max": "10",
+        "setup_daily_max": "0"
       },
       "context": {
         "contact_type": "customer,lead,partner,vendor"
@@ -162,6 +185,28 @@
         "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.",

package/content/integrations/erp.json

@@ -18,12 +18,24 @@
         "type": "text",
         "placeholder": "Leave empty for local SQLite",
         "optional": true
+      },
+      {
+        "key": "mode",
+        "label": "Mode (optional)",
+        "type": "text",
+        "placeholder": "simulation (default) — live needs an adapter for your ERP",
+        "optional": true
       }
     ],
     "envMapping": {
-      "DATABASE_URL": "databaseUrl"
+      "DATABASE_URL": "databaseUrl",
+      "ERP_MODE": "mode"
     }
   },
+  "simulation": {
+    "field": "mode",
+    "default": "simulation"
+  },
   "personalDefault": true,
   "oauth": null,
   "toolGating": {
@@ -115,6 +127,14 @@
           "action_type": "order"
         },
         "actionLabel": "Quote converted to order"
+      },
+      "load_simulation": {
+        "executionMapping": {},
+        "staticExecution": {
+          "action_type": "setup"
+        },
+        "actionLabel": "Test data loaded",
+        "hideUnlessAuthorized": true
       }
     }
   },
@@ -131,7 +151,8 @@
         "order_value_daily_max": "0",
         "quote_daily_max": "20",
         "send_daily_max": "0",
-        "order_daily_max": "0"
+        "order_daily_max": "0",
+        "setup_daily_max": "0"
       },
       "context": {
         "currency": "EUR"
@@ -156,7 +177,8 @@
         "order_value_daily_max": "50000",
         "quote_daily_max": "50",
         "send_daily_max": "20",
-        "order_daily_max": "10"
+        "order_daily_max": "10",
+        "setup_daily_max": "0"
       },
       "context": {
         "currency": "EUR"
@@ -168,6 +190,32 @@
         "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.",

package/content/integrations/index.json

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

package/content/integrations/mail.json

@@ -0,0 +1,148 @@
+{
+  "id": "mail",
+  "name": "Email (simulation)",
+  "version": "1.0.0",
+  "description": "Simulated inbox for testing an agent's email replies — nothing leaves the laptop",
+  "icon": "mail",
+  "profile": "email",
+  "npmPackage": "@humanagencyp/email-mcp",
+  "mcp": {
+    "command": "email-mcp",
+    "args": []
+  },
+  "credentials": {
+    "fields": [
+      {
+        "key": "mode",
+        "label": "Mode (optional)",
+        "type": "text",
+        "placeholder": "simulation (default) — live needs a mailbox adapter",
+        "optional": true
+      },
+      {
+        "key": "databaseUrl",
+        "label": "Database URL (optional)",
+        "type": "text",
+        "placeholder": "Leave empty for local SQLite",
+        "optional": true
+      }
+    ],
+    "envMapping": {
+      "EMAIL_MODE": "mode",
+      "DATABASE_URL": "databaseUrl"
+    }
+  },
+  "simulation": {
+    "field": "mode",
+    "default": "simulation"
+  },
+  "personalDefault": false,
+  "oauth": null,
+  "toolGating": {
+    "default": {
+      "executionMapping": {},
+      "staticExecution": {}
+    },
+    "overrides": {
+      "list_messages": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "get_message": {
+        "category": "read",
+        "boundField": "read_access",
+        "requiredValue": "unlimited"
+      },
+      "send_message": {
+        "executionMapping": {
+          "to": [
+            {
+              "field": "recipient_count",
+              "transform": "length"
+            },
+            {
+              "field": "allowed_recipients",
+              "transform": "join"
+            },
+            {
+              "field": "allowed_domains",
+              "transform": "join_domains"
+            }
+          ]
+        },
+        "staticExecution": {
+          "action_type": "send"
+        },
+        "actionLabel": "Email sent"
+      },
+      "load_simulation": {
+        "executionMapping": {},
+        "staticExecution": {
+          "action_type": "setup"
+        },
+        "actionLabel": "Test data loaded",
+        "hideUnlessAuthorized": true
+      }
+    }
+  },
+  "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": [
+    {
+      "title": "Ready to use",
+      "description": "This connector stores a simulated inbox locally on your machine. Nothing is sent anywhere until you load test data with a separate, reviewed setup mandate."
+    },
+    {
+      "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."
+    }
+  ]
+}