@suveren/gateway 0.17.0 → 0.18.1

package/bin/suveren-gateway.js

@@ -15,7 +15,7 @@ import { createConnection } from 'node:net';
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
 import { homedir, platform, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { buildLaunchAgentPlist, buildMacLauncher, buildSystemdUnit, buildWindowsTaskXml } from '../lib/autostart-templates.mjs';
 import { DEFAULT_AS_URL, readConfig, writeConfig, validateAsUrl, validateCaFile, validateProxyUrl, validatePinTls, resolveAsUrl, resolvePinTls, resolvePinTlsExpectedFingerprint, resolveSimulation } from '../lib/config.mjs';
 import { createInterface } from 'node:readline/promises';
@@ -1362,6 +1362,27 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+/**
+ * `suveren-gateway verify-report <file> [--key <hex>] [--online]` — offline
+ * verification of an "Export with proof" report file (work-plan R6).
+ * Delegates entirely to the compiled `dist/mcp-server/report-verify-cli.mjs`
+ * (built from apps/mcp-server's OWN tsup entry, next to dist/mcp-server/
+ * http.mjs) — this script never reimplements the signature-checking logic.
+ * Exit codes are documented there (`--help`): 0 valid+key confirmed,
+ * 1 invalid, 2 valid but key unconfirmed.
+ */
+async function verifyReport(args) {
+  const modPath = join(PKG_ROOT, 'dist', 'mcp-server', 'report-verify-cli.mjs');
+  if (!existsSync(modPath)) {
+    console.error(`verify-report is unavailable: ${modPath} not found.`);
+    console.error('This checkout has no built mcp-server bundle — install the published package, or build one first.');
+    process.exitCode = 1;
+    return;
+  }
+  const mod = await import(pathToFileURL(modPath).href);
+  process.exitCode = await mod.runVerifyReportCli(args);
+}
+
 function printHelp() {
   console.log(`suveren-gateway — Suveren gateway (Human Agency Protocol)
 
@@ -1388,6 +1409,9 @@ Usage:
   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 verify-report <file> [--key <hex>] [--online]
+                                              Verify an "Export with proof" report file offline
+                                              (see \`suveren-gateway verify-report --help\`)
   suveren-gateway help                        Print this help
 
 Environment:
@@ -1426,6 +1450,7 @@ async function main() {
     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 'verify-report': await verifyReport(argv.slice(1)); break;
     case 'help':
     case '--help':
     case '-h':

package/content/guides/1-interview.md

@@ -0,0 +1,31 @@
+# Interview
+
+Learn the company, the team and the work, and collect real cases. Nothing is loaded or proposed in this step.
+
+You ask; the person answers and checks. Ask one topic at a time and write down what you learn.
+
+## What to ask, in this order
+
+1. **Company:** what it sells, to whom, in which currency, and which systems it uses. The systems connected to this gateway are listed in the header above; ask about the ones that matter for the work.
+2. **Department and team:** who does the work today, what a normal day looks like, what must never happen.
+3. **The work to test:** which requests come in (for example quote requests, orders, questions), how many, how fast they are answered today, and what a good answer looks like.
+4. **Order of systems:** whether the team follows a fixed sequence across systems — for example: always look up the customer in the CRM before quoting in the ERP, and log the reply in the CRM after sending. Which step must come first, which may be skipped. This becomes the agent's process and a rule in its brief.
+5. **Real cases:** 5–10 recent examples, each with the request as it arrived and the reply that was actually sent. The person pastes or forwards them.
+6. **Rules that are not written down:** discounts, credit limits, who may promise delivery dates, when to escalate and to whom.
+
+## Renaming
+
+Before anything else happens, propose new names for every person, company and email domain in the cases. Keep amounts, products and dates realistic. Use `.example` domains (for example `einkauf@huber.example`). The person checks the renamed cases; change them until they agree.
+
+## Result of this step
+
+- A short written summary: company, team, the work, the order of systems, the rules.
+- The renamed cases.
+
+Both confirmed by the person. The summary feeds the agent brief and the mandates; the cases feed the test data.
+
+## Ask, don't guess
+
+If a rule or a step is unclear, ask the person. Never invent a rule, a limit or a step to fill a gap.
+
+Next: **package**.

package/content/guides/2-package.md

@@ -0,0 +1,30 @@
+# Package
+
+Turn the confirmed cases into test data and load it into the simulated systems.
+
+## Build the package
+
+One package feeds every simulated system. Its format, and how to build a good one, is described in the `load_simulation` tool of each simulated system — read it there; it is the authority. In short: the company's `name` and `currency`, the `customers`, `products` and `contacts` the cases need, and the `cases` themselves (each request as it arrived and the reply that was actually sent).
+
+- Include every customer, product and contact a case mentions, with stock, prices and credit limits that make each case answerable the way it really was.
+- Use only the renamed cases.
+- Show the person the package before loading it; load only after they agree.
+
+## Load
+
+- Loading needs a setup mandate for each system (see **mandates**). The working AI's mandates must never allow loading.
+- Call `load_simulation` in each simulated system with the same package.
+- A load only works into an empty system. Incoming requests are dated within the hour before the load, in case order.
+
+## Run again
+
+To run the same cases again under a different setup, or other cases under the same setup:
+
+1. `clear_simulation` in each system — this deletes all test data, including the record of what happened.
+2. `load_simulation` again.
+
+Clear and load each count against the setup mandate's daily limit, so one re-run costs two per system. If the limit is too small, propose a new setup mandate with a higher limit.
+
+The real replies stay inside the simulated email system. They are never shown to the working AI; they exist for comparing afterwards.
+
+Next: **mandates**.

package/content/guides/3-mandates.md

@@ -0,0 +1,35 @@
+# Mandates
+
+Propose the mandates the setup and the working AI need. You propose with `create_mandate`; the person approves each one on its own; only then is it created.
+
+## Ask first
+
+Before proposing any mandate, ask the person which steps they want to approve themselves. Their answer wins over everything below.
+
+## The standard (when the person has no preference)
+
+- **Steps the customer would see** — replies, sent quotes, orders — start in **review** mode: each one waits for the person's approval.
+- **Internal steps** — looking up and noting things in the CRM, drafting quotes, loading test data — run **automatically** within limits.
+
+Apply this to whatever systems are connected: the header above lists each system with its action types and tools. Judge from the action type and its tools whether the customer would see the result. When unsure, ask.
+
+## Rules
+
+- **One mandate per system.** Split a system into several mandates only when the team has different rules for different tasks. A mode applies to a whole mandate, so different modes for different steps of one system mean separate mandates (for example: drafting quotes automatically, sending quotes in review).
+- **Setup and work are separate.** Setup mandates allow loading and clearing test data and nothing else. The working AI's mandates allow no loading or clearing (setup limit 0).
+- **Start strict.** Where the team has not said otherwise, propose review mode or low caps. The person can loosen a mandate later by replacing it.
+- **Limits come from the interview:** amounts, discounts, daily counts, allowed recipients. Do not invent them; ask.
+- **Intent:** write why, goal and watch-outs in the person's words, in the language the team uses. It is signed with the mandate and the working AI follows it.
+- **Teams:** in a team, the person must be an approver for the profile. `create_mandate` refuses at once if not; tell the person who can fix it (a team admin).
+- **Workspace:** without `team`, a mandate goes where the person's Delegation mandate is. If they hold Delegation mandates in several workspaces, ask which one and pass it (`team`: a team's name, or `"personal"`).
+- **Reporting:** never propose a `reporting` mandate for the working AI during a run (see **risks**).
+
+## Example (only an example)
+
+- Setup, per system: automatic, setup limit 4–6 per day, everything else 0.
+- CRM: automatic, with daily limits.
+- Sales, drafting quotes: automatic, within value and discount caps.
+- Sales, sending quotes and orders: review.
+- Email replies: review, recipients limited to the customers' domains.
+
+Next: **brief**.

package/content/guides/4-brief.md

@@ -0,0 +1,30 @@
+# Brief
+
+Propose the agent brief — the standing instructions the working AI starts every session with. You propose with `set_agent_brief`; the person approves; it applies from the working AI's next session.
+
+## What goes in
+
+From the interview:
+
+- **Who the AI works for:** the company, the team, the person.
+- **The job:** which requests it handles and what a good outcome is.
+- **The process:** the steps in order, including the order of systems from the interview, written as a rule (for example: "Always look up the customer in the CRM before preparing a quote.").
+- **House rules:** tone, language, discounts, credit, what to escalate and to whom.
+- **Hard lines:** what it must never do, even where a mandate would allow it.
+- **When unsure, ask:** a missing rule or an unclear step goes to the person, never to a guess.
+
+Write the brief in the language the team uses.
+
+## What stays out
+
+- Anything that reveals a test: no "simulation", "test case", "expected reply" or similar words.
+- The real replies from the cases.
+- Secrets, passwords, keys.
+
+## Limits
+
+- At most 16 KB.
+- It replaces the whole brief each time — always write the complete brief, not a change.
+- The person approves every version.
+
+Next: **agent-process**.

package/content/guides/5-agent-process.md

@@ -0,0 +1,39 @@
+# Agent process
+
+Help the person set up the working AI's process in its own client. The process is the working AI's work, not the gateway's: the gateway only grants and checks what it may do.
+
+## Write the process as steps
+
+From the interview, for example:
+
+1. Read new messages in the inbox.
+2. Look up the customer in the CRM.
+3. Check stock and price in the ERP.
+4. Prepare the quote.
+5. Reply to the customer.
+
+Keep a fixed order of systems from the interview exactly as given; it is also a rule in the brief. The person confirms the steps.
+
+## Where it lives
+
+- In the working AI's client, as its standing instructions for this work, connected to this gateway.
+- In a separate conversation or project from this setup conversation.
+
+## What starts a run
+
+- The person asks (for example: "Work the new requests.").
+- Or a scheduled or triggered run, if the client offers one. Check what the person's client offers today; do not assume.
+
+## When a step is unclear
+
+The working AI stops and asks the person. It never fills a gap by guessing.
+
+## Claude Desktop
+
+Help the person connect the client to this gateway (the gateway's MCP address) and put the steps into the client's standing instructions for this work. Check the client's current settings with the person; menus change between versions.
+
+## ChatGPT
+
+Same as above: connect the gateway if the person's plan and client support custom MCP connectors, and add the steps as instructions. If connecting is not possible, say so — the working AI cannot be tested without the gateway.
+
+Next: **risks**, then start a run.

package/content/guides/6-risks.md

@@ -0,0 +1,14 @@
+# Risks
+
+What can make a test say more than it should, and what to do about each. Read this once at the start and again before every run.
+
+| Risk | Why it matters | What to do |
+| --- | --- | --- |
+| The client remembers earlier runs | A re-run of the same cases is no longer a fresh test | Start every run in a new conversation; turn the client's memory off for the working AI |
+| The working AI learns it is a test | It may behave differently | Never give it a `reporting` mandate during a run — its tools list the cases. Grant `reporting` only after the run, or to a separate AI session that only writes the report. Keep test words out of the brief |
+| Setup and work in the same session | Setup tools and the real replies stay in the working AI's context | Use separate conversations for setup and for work |
+| Mandates too loose | A wrong result can look like success | Start in review mode or with low caps; loosen by replacing the mandate |
+| Proposals are stored readable on the Authority Server | The content of every proposal, including intents, can be read there | Test data and renamed cases only — never real customer data in a setup |
+| Setup limit too low | A clear without the following load leaves empty systems | Use a setup limit of 4–6 per day; clear and load in one go |
+
+Next: start a run — the person asks the working AI to work the new requests.

package/dist/control-plane/index.mjs

@@ -549,6 +549,56 @@ async function getLocalEvidence() {
   if (!res.ok) throw new Error(`Failed to fetch local evidence: ${res.status}`);
   return res.json();
 }
+var McpLockedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpLockedError";
+  }
+};
+async function reportRequest(path, init) {
+  const res = await fetch(`${MCP_BASE}${path}`, { ...init, headers: internalHeaders() });
+  if (res.status === 503) {
+    const err = await res.json().catch(() => ({ error: "Vault locked" }));
+    throw new McpLockedError(err.error ?? "Vault locked");
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: "Unknown error" }));
+    throw new Error(err.error ?? `Request to ${path} failed: ${res.status}`);
+  }
+  return res.json();
+}
+async function getReport() {
+  return reportRequest("/internal/report");
+}
+async function saveReport(html) {
+  return reportRequest("/internal/report", {
+    method: "POST",
+    body: JSON.stringify({ html })
+  });
+}
+async function recheckReport() {
+  return reportRequest("/internal/report/recheck", { method: "POST" });
+}
+async function exportReport(gatewayVersion) {
+  const res = await fetch(`${MCP_BASE}/internal/report/export?gatewayVersion=${encodeURIComponent(gatewayVersion)}`, {
+    headers: internalHeaders()
+  });
+  if (res.status === 503) {
+    const err = await res.json().catch(() => ({ error: "Vault locked" }));
+    throw new McpLockedError(err.error ?? "Vault locked");
+  }
+  if (res.status === 404) {
+    const err = await res.json().catch(() => ({ error: "No report to export" }));
+    throw new Error(err.error ?? "No report to export");
+  }
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: `Export failed: ${res.status}` }));
+    throw new Error(err.error ?? `Export failed: ${res.status}`);
+  }
+  const html = await res.text();
+  const filename = /filename="([^"]+)"/.exec(res.headers.get("content-disposition") ?? "")?.[1] ?? "suveren-report.html";
+  return { html, filename };
+}
 async function getMcpHealth() {
   const res = await fetch(`${MCP_BASE}/health`);
   if (!res.ok) throw new Error("MCP server unreachable");
@@ -3431,10 +3481,68 @@ function createEvidenceRouter() {
   return router;
 }
 
-// src/routes/decrypt-intent.ts
+// src/routes/report.ts
 import { Router as Router11 } from "express";
-function createDecryptIntentRouter(vault2) {
+function handleError(res, err) {
+  if (err instanceof McpLockedError) {
+    res.status(503).json({ error: err.message });
+    return;
+  }
+  res.status(502).json({
+    error: "Report unavailable",
+    detail: err instanceof Error ? err.message : String(err)
+  });
+}
+function createReportRouter(getGatewayVersion) {
   const router = Router11();
+  router.get("/", async (_req, res) => {
+    try {
+      res.json(await getReport());
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.post("/", async (req, res) => {
+    const html = req.body?.html;
+    if (typeof html !== "string" || !html.trim()) {
+      res.status(400).json({ error: "Missing required field: html (non-empty string)" });
+      return;
+    }
+    try {
+      res.json(await saveReport(html));
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.post("/recheck", async (_req, res) => {
+    try {
+      res.json(await recheckReport());
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.get("/export", async (_req, res) => {
+    try {
+      const { html, filename } = await exportReport(getGatewayVersion());
+      res.setHeader("Content-Type", "text/html; charset=utf-8").setHeader("Content-Disposition", `attachment; filename="${filename}"`).setHeader("Cache-Control", "no-store").send(html);
+    } catch (err) {
+      if (err instanceof McpLockedError) {
+        res.status(503).json({ error: err.message });
+        return;
+      }
+      res.status(502).json({
+        error: "Export failed",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+    }
+  });
+  return router;
+}
+
+// src/routes/decrypt-intent.ts
+import { Router as Router12 } from "express";
+function createDecryptIntentRouter(vault2) {
+  const router = Router12();
   router.post("/", async (req, res) => {
     const { intentCiphertext, encryptedKey, approverId } = req.body;
     if (typeof intentCiphertext !== "string" || intentCiphertext.length === 0) {
@@ -3610,7 +3718,7 @@ data: ${data}
 }
 
 // src/routes/gateway-settings.ts
-import { Router as Router12 } from "express";
+import { Router as Router13 } from "express";
 
 // src/lib/gateway-settings.ts
 import { readFileSync as readFileSync10, writeFileSync as writeFileSync6, mkdirSync as mkdirSync6 } from "fs";
@@ -3646,7 +3754,7 @@ function writeSettings(patch, dataDir) {
 
 // src/routes/gateway-settings.ts
 function createGatewaySettingsRouter() {
-  const router = Router12();
+  const router = Router13();
   router.get("/", (_req, res) => {
     res.json(readSettings());
   });
@@ -3669,7 +3777,7 @@ function createGatewaySettingsRouter() {
 }
 
 // src/routes/archived-mandates.ts
-import { Router as Router13 } from "express";
+import { Router as Router14 } from "express";
 
 // src/lib/archived-mandates-store.ts
 import { readFileSync as readFileSync11, writeFileSync as writeFileSync7, mkdirSync as mkdirSync7, renameSync } from "fs";
@@ -3712,7 +3820,7 @@ function unarchiveMandate(id, dataDir) {
 
 // src/routes/archived-mandates.ts
 function createArchivedMandatesRouter(dataDir) {
-  const router = Router13();
+  const router = Router14();
   router.get("/", (_req, res) => {
     res.json({ archived: readArchived(dataDir) });
   });
@@ -3734,7 +3842,7 @@ function createArchivedMandatesRouter(dataDir) {
 }
 
 // src/routes/internal-events.ts
-import { Router as Router14 } from "express";
+import { Router as Router15 } from "express";
 import { timingSafeEqual as timingSafeEqual2 } from "crypto";
 var ALLOWED = ["proposal-added", "action-approval-needed"];
 var SESSION_EXPIRED = "session-expired";
@@ -3749,7 +3857,7 @@ function secretMatches(provided, expected) {
   return timingSafeEqual2(a, b);
 }
 function createInternalEventsRouter(getSecret, onSessionExpired, onAsKeyMismatch, onAsTlsMismatch) {
-  const router = Router14();
+  const router = Router15();
   router.post("/event", (req, res) => {
     if (!secretMatches(req.headers["x-internal-secret"], getSecret())) {
       res.status(401).json({ error: "Unauthorized" });
@@ -3783,7 +3891,7 @@ function createInternalEventsRouter(getSecret, onSessionExpired, onAsKeyMismatch
 }
 
 // src/routes/internal-mandate.ts
-import { Router as Router15 } from "express";
+import { Router as Router16 } from "express";
 import { timingSafeEqual as timingSafeEqual3, randomUUID } from "crypto";
 
 // src/lib/mandate-ceremony.ts
@@ -3832,13 +3940,24 @@ function approverPubkeys(body) {
   if (!map || typeof map !== "object" || Array.isArray(map)) return [];
   return Object.entries(map).filter((e) => typeof e[1] === "string" && e[1].length > 0).map(([userId, publicKey]) => ({ userId, publicKey }));
 }
+async function delegationWorkspace(deps, groups) {
+  const personal = groups.find((g) => g.isPersonal);
+  const mine = await deps.as("GET", "/api/attestations/mine?status=active");
+  const rows = mine.status === 200 ? mine.body?.attestations ?? [] : [];
+  const ids = new Set(rows.filter((r) => r.profileId && shortOf(r.profileId) === "delegation" && r.groupId).map((r) => r.groupId));
+  const found = groups.filter((g) => ids.has(g.id));
+  if (found.length === 0) return personal;
+  if (found.length === 1) return found[0];
+  const names = found.map((g) => g.isPersonal ? "the personal workspace" : `"${g.name}"`).join(", ");
+  refuse(`Delegation mandates exist in several workspaces (${names}): say which in \`team\` \u2014 a team's name, or "personal".`);
+}
 async function planMandate(req, deps) {
   const user = deps.user;
   if (!user) refuse("The gateway is not signed in.");
   const groupsRes = await deps.as("GET", "/api/groups");
   const groups = groupsRes.body?.groups ?? [];
-  const group = req.team ? groups.find((g) => !g.isPersonal && (g.id === req.team || g.name === req.team)) : groups.find((g) => g.isPersonal);
-  if (!group) refuse(req.team ? `You are not a member of a team "${req.team}".` : "No personal workspace found.");
+  const group = req.team === "personal" ? groups.find((g) => g.isPersonal) : req.team ? groups.find((g) => !g.isPersonal && (g.id === req.team || g.name === req.team)) : await delegationWorkspace(deps, groups);
+  if (!group) refuse(req.team && req.team !== "personal" ? `You are not a member of a team "${req.team}".` : "No personal workspace found.");
   const isPersonal = !!group.isPersonal;
   const profile = await resolveProfile(deps.as, req.profile);
   const name = profile.name ?? shortOf(profile.id);
@@ -3945,7 +4064,7 @@ function secretMatches2(provided, expected) {
   return a.length === b.length && timingSafeEqual3(a, b);
 }
 function createInternalMandateRouter(getSecret, deps) {
-  const router = Router15();
+  const router = Router16();
   router.post("/mandate", async (req, res) => {
     if (!secretMatches2(req.header("X-Internal-Secret") ?? void 0, getSecret())) {
       res.status(401).json({ error: "unauthorized" });
@@ -4530,6 +4649,7 @@ app.use("/api/archived-mandates", jsonParser, authGuard, createArchivedMandatesR
 app.use("/api/encrypt-intent", jsonParser, authGuard, createEncryptIntentRouter());
 app.use("/api/evidence-export", authGuard, createEvidenceExportRouter(SP_URL, vault, DATA_DIR, lockAsTlsMismatch));
 app.use("/api/evidence", authGuard, createEvidenceRouter());
+app.use("/api/report", jsonParser, authGuard, createReportRouter(() => RUNNING_VERSION));
 app.use("/api/decrypt-intent", jsonParser, authGuard, createDecryptIntentRouter(vault));
 app.use("/api/approved-intents", jsonParser, authGuard, createApprovedIntentsRouter(vault));
 app.put("/integrations/:id/read-policy", jsonParser, authGuard, async (req, res) => {