@suveren/gateway 0.16.0 → 0.17.0

package/dist/control-plane/index.mjs

@@ -40,6 +40,8 @@ var Vault = class {
    * disk, gone the moment the process restarts or the vault locks.
    */
   spSessionExpiresAt = null;
+  /** Who the current AS session belongs to (from the login response). Never persisted. */
+  sessionUser = null;
   /** Set by lockExpired(); cleared by any fresh unseal (a new login). */
   lockedReason = null;
   constructor(dataDir) {
@@ -97,6 +99,7 @@ var Vault = class {
     this.spSessionCookie = null;
     this.unsealedBy = null;
     this.spSessionExpiresAt = null;
+    this.sessionUser = null;
     this.lockedReason = null;
   }
   /**
@@ -149,6 +152,13 @@ var Vault = class {
   getSessionExpiresAt() {
     return this.spSessionExpiresAt;
   }
+  /** The signed-in person, set at login from the AS session response; cleared with the session. */
+  setSessionUser(user) {
+    this.sessionUser = user;
+  }
+  getSessionUser() {
+    return this.sessionUser;
+  }
   /**
    * Check if the vault was created by a different API key.
    * Tries to decrypt the first credential — if it fails, keys don't match.
@@ -414,6 +424,11 @@ async function runCommittedProposals() {
     headers: internalHeaders()
   });
 }
+async function getToolDisplay() {
+  const res = await fetch(`${MCP_BASE}/internal/tool-display`, { headers: internalHeaders() });
+  if (!res.ok) throw new Error(`MCP tool-display failed: ${res.status}`);
+  return res.json();
+}
 async function getIntegrations() {
   const res = await fetch(`${MCP_BASE}/internal/integrations`, {
     headers: internalHeaders()
@@ -1726,6 +1741,10 @@ function createAuthRouter(vault2, logoutAuth, loginRateLimit2, onSessionEstablis
       }
       const sessionExpiresAt = typeof data.sessionExpiresAt === "number" ? data.sessionExpiresAt : null;
       vault2.setSessionExpiresAt(sessionExpiresAt);
+      const sessionUser = data.user;
+      vault2.setSessionUser(
+        typeof sessionUser?.id === "string" && typeof sessionUser?.did === "string" ? { id: sessionUser.id, did: sessionUser.did } : null
+      );
       onSessionEstablished?.();
       if (sessionCookie) {
         try {
@@ -3087,7 +3106,26 @@ function notify(title, message, platform = process.platform, url) {
 
 // src/routes/encrypt-intent.ts
 import { Router as Router7 } from "express";
+
+// src/lib/intent-encryption.ts
 import { computeIntentDisclosureHash } from "@hap/core";
+async function encryptIntentForRecipients(intent, recipients) {
+  const parsed = recipients.map(({ userId, publicKey }) => {
+    const bytes = new Uint8Array(Buffer.from(publicKey, "base64"));
+    if (bytes.length !== 32) throw new Error(`publicKey for userId "${userId}" must be 32 bytes (X25519); got ${bytes.length}`);
+    return { userId, publicKey: bytes };
+  });
+  const encrypted = await encryptForRecipients(intent, parsed);
+  const encryptedKeys = {};
+  for (const [userId, wrap] of Object.entries(encrypted.encryptedKeys)) {
+    encryptedKeys[userId] = { ct: Buffer.from(wrap.ct).toString("base64"), enc: Buffer.from(wrap.enc).toString("base64") };
+  }
+  const intentCiphertext = Buffer.from(encrypted.intentCiphertext).toString("base64");
+  const approversFrozen = parsed.map((r) => r.userId);
+  return { intentCiphertext, encryptedKeys, approversFrozen, intentDisclosureHash: computeIntentDisclosureHash(intentCiphertext, approversFrozen) };
+}
+
+// src/routes/encrypt-intent.ts
 function createEncryptIntentRouter() {
   const router = Router7();
   router.post("/", async (req, res) => {
@@ -3125,23 +3163,10 @@ function createEncryptIntentRouter() {
       parsed.push({ userId, publicKey: pubBytes });
     }
     try {
-      const encrypted = await encryptForRecipients(intent, parsed);
-      const encryptedKeys = {};
-      for (const [userId, wrap] of Object.entries(encrypted.encryptedKeys)) {
-        encryptedKeys[userId] = {
-          ct: Buffer.from(wrap.ct).toString("base64"),
-          enc: Buffer.from(wrap.enc).toString("base64")
-        };
-      }
-      const intentCiphertextB64 = Buffer.from(encrypted.intentCiphertext).toString("base64");
-      const approversFrozen = parsed.map((r) => r.userId);
-      const intentDisclosureHash = computeIntentDisclosureHash(intentCiphertextB64, approversFrozen);
-      res.json({
-        intentCiphertext: intentCiphertextB64,
-        encryptedKeys,
-        approversFrozen,
-        intentDisclosureHash
-      });
+      res.json(await encryptIntentForRecipients(
+        intent,
+        parsed.map((r) => ({ userId: r.userId, publicKey: Buffer.from(r.publicKey).toString("base64") }))
+      ));
     } catch (err) {
       console.error("[Control Plane] encrypt-intent error:", err);
       res.status(500).json({ error: err instanceof Error ? err.message : "Encryption failed" });
@@ -3757,6 +3782,201 @@ function createInternalEventsRouter(getSecret, onSessionExpired, onAsKeyMismatch
   return router;
 }
 
+// src/routes/internal-mandate.ts
+import { Router as Router15 } from "express";
+import { timingSafeEqual as timingSafeEqual3, randomUUID } from "crypto";
+
+// src/lib/mandate-ceremony.ts
+import {
+  allowedCommitmentModes,
+  computeBoundsHash,
+  computeContextHash,
+  computeIntentHash,
+  isCommitmentModeAllowed,
+  validateBoundsParams,
+  validateContextParams
+} from "@hap/core";
+var MandateRefused = class extends Error {
+};
+var INTENT_MAX = 2e3;
+var shortOf = (id) => id.replace(/@.*$/, "").split("/").pop() ?? id;
+var versionOf = (id) => id.split("@")[1] ?? "";
+function refuse(msg) {
+  throw new MandateRefused(msg);
+}
+async function resolveProfile(as, requested) {
+  let id = requested.trim();
+  if (!id.includes("@")) {
+    const list = await as("GET", "/api/profiles");
+    const matches = (list.body?.profiles ?? []).filter((p) => shortOf(p.id) === id);
+    if (matches.length === 0) refuse(`Unknown profile "${requested}".`);
+    matches.sort((a, b) => versionOf(b.id).localeCompare(versionOf(a.id), void 0, { numeric: true }));
+    id = matches[0].id;
+  }
+  const res = await as("GET", `/api/profiles/${encodeURIComponent(id)}`);
+  if (res.status !== 200 || !res.body?.id) refuse(`Unknown profile "${requested}".`);
+  return res.body;
+}
+function scalarRecord(label, value) {
+  if (value === void 0 || value === null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) refuse(`\`${label}\` must be an object.`);
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v !== "string" && typeof v !== "number") refuse(`\`${label}.${k}\` must be a string or a number.`);
+    out[k] = v;
+  }
+  return out;
+}
+function approverPubkeys(body) {
+  const map = body?.pubkeys;
+  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 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 isPersonal = !!group.isPersonal;
+  const profile = await resolveProfile(deps.as, req.profile);
+  const name = profile.name ?? shortOf(profile.id);
+  let approvers = [];
+  if (!isPersonal) {
+    const cfg = await deps.as("GET", `/api/groups/${encodeURIComponent(group.id)}/profile-config/${encodeURIComponent(profile.id)}`);
+    approvers = (cfg.status === 200 ? cfg.body?.config?.approvers : void 0) ?? [];
+    if (approvers.length === 0) refuse(`${name} is not enabled in "${group.name}": a team admin must name who may give ${name} mandates.`);
+    if (!approvers.includes(user.id)) refuse(`Only ${name}'s approvers in "${group.name}" can give this mandate, and the signed-in person is not one of them.`);
+  }
+  const bounds = { ...scalarRecord("limits", req.limits), profile: profile.id };
+  const bv = validateBoundsParams(bounds, profile);
+  const errors = [...bv.errors];
+  for (const [field, value] of Object.entries(bounds)) {
+    const bt = profile.boundsSchema?.fields[field]?.boundType;
+    if (bt?.kind === "enum" && Array.isArray(bt.values) && !bt.values.includes(String(value))) {
+      errors.push(`Field "${field}" must be one of ${bt.values.join(", ")}.`);
+    }
+  }
+  const context = scalarRecord("scope", req.scope);
+  errors.push(...validateContextParams(context, profile).errors);
+  if (errors.length) refuse(`The mandate does not fit profile ${profile.id}: ${errors.join(" ")}`);
+  if (!isCommitmentModeAllowed(profile, req.mode)) {
+    refuse(`Profile ${profile.id} allows mode ${allowedCommitmentModes(profile).join(" or ") || "none"}, not "${req.mode}".`);
+  }
+  const ttlSeconds = req.durationHours === void 0 ? profile.ttl.default : Math.round(req.durationHours * 3600);
+  if (!(ttlSeconds > 0)) refuse("`duration_hours` must be positive.");
+  if (ttlSeconds > profile.ttl.max) refuse(`At most ${profile.ttl.max / 3600} hours for profile ${profile.id}.`);
+  const intent = typeof req.intent === "string" ? req.intent.trim() : "";
+  if (!intent) refuse("`intent` is required \u2014 the why, goal and watch-outs, in the person's words.");
+  if (intent.length > INTENT_MAX) refuse(`\`intent\` is ${intent.length} characters; the limit is ${INTENT_MAX}.`);
+  return {
+    groupId: group.id,
+    groupName: group.name,
+    isPersonal,
+    domain: isPersonal ? "owner" : user.id,
+    profile,
+    bounds,
+    context,
+    intent,
+    mode: req.mode,
+    ttlSeconds,
+    title: (req.title ?? "").trim() || `${name} (proposed by AI)`,
+    approvers
+  };
+}
+async function createMandate(req, deps) {
+  const plan = await planMandate(req, deps);
+  const user = deps.user;
+  const boundsHash = computeBoundsHash(plan.bounds, plan.profile);
+  const contextHash = computeContextHash(plan.context, plan.profile);
+  const intentHash = computeIntentHash(plan.intent);
+  const ecHash = computeIntentHash(JSON.stringify({ profile: plan.profile.id, domain: plan.domain, group: plan.groupId }));
+  let enc;
+  if (!plan.isPersonal) {
+    const keys = await deps.as(
+      "GET",
+      `/api/groups/${encodeURIComponent(plan.groupId)}/profile-config/${encodeURIComponent(plan.profile.id)}/approvers/pubkeys`
+    );
+    const recipients = approverPubkeys(keys.body);
+    if (recipients.length > 0) enc = await deps.encrypt(plan.intent, recipients);
+  }
+  const authorizationId = deps.newAuthorizationId();
+  const res = await deps.as("POST", "/api/as/attest", {
+    authorization_id: authorizationId,
+    profile_id: plan.profile.id,
+    bounds: plan.bounds,
+    bounds_hash: boundsHash,
+    context_hash: contextHash,
+    domain: plan.domain,
+    did: user.did,
+    gate_content_hashes: { intent: intentHash },
+    execution_context_hash: ecHash,
+    group_id: plan.groupId,
+    ttl: plan.ttlSeconds,
+    commitment_mode: plan.mode,
+    title: plan.title,
+    intent_ciphertext: enc?.intentCiphertext,
+    encrypted_keys: enc?.encryptedKeys,
+    approvers_frozen: enc?.approversFrozen,
+    intent_disclosure_hash: enc?.intentDisclosureHash
+  });
+  if (res.status >= 300) {
+    const why = res.body?.message ?? res.body?.detail ?? res.body?.error ?? `status ${res.status}`;
+    refuse(`The Authority Server refused the mandate: ${why}`);
+  }
+  try {
+    await deps.deliverGateContent({ authorizationId, boundsHash, contextHash, context: plan.context, gateContent: { intent: plan.intent } });
+  } catch (err) {
+    await deps.as("POST", `/api/authorizations/${encodeURIComponent(authorizationId)}/revoke`, {
+      reason: "Auto-revoked: gate content delivery failed"
+    }).catch(() => {
+    });
+    refuse(`The mandate was signed but its intent could not be delivered to the gateway, so it was revoked. (${err instanceof Error ? err.message : String(err)})`);
+  }
+  return { authorizationId, plan };
+}
+
+// src/routes/internal-mandate.ts
+function secretMatches2(provided, expected) {
+  if (!expected || !provided) return false;
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual3(a, b);
+}
+function createInternalMandateRouter(getSecret, deps) {
+  const router = Router15();
+  router.post("/mandate", async (req, res) => {
+    if (!secretMatches2(req.header("X-Internal-Secret") ?? void 0, getSecret())) {
+      res.status(401).json({ error: "unauthorized" });
+      return;
+    }
+    const { dryRun, request } = req.body ?? {};
+    if (!request || typeof request !== "object") {
+      res.status(400).json({ error: "missing request" });
+      return;
+    }
+    const d = { ...deps(), newAuthorizationId: () => `authz_${randomUUID()}` };
+    try {
+      if (dryRun === true) {
+        const plan2 = await planMandate(request, d);
+        res.json({ ok: true, groupName: plan2.groupName, profileId: plan2.profile.id, mode: plan2.mode, ttlSeconds: plan2.ttlSeconds });
+        return;
+      }
+      const { authorizationId, plan } = await createMandate(request, d);
+      res.json({ ok: true, authorizationId, profileId: plan.profile.id, groupName: plan.groupName, mode: plan.mode, ttlSeconds: plan.ttlSeconds });
+    } catch (err) {
+      if (err instanceof MandateRefused) {
+        res.status(422).json({ error: "mandate_refused", message: err.message });
+        return;
+      }
+      console.error("[Control Plane] /internal/mandate failed:", err);
+      res.status(500).json({ error: "internal", message: err instanceof Error ? err.message : String(err) });
+    }
+  });
+  return router;
+}
+
 // src/lib/notification-dispatcher.ts
 var TRIGGER_EVENTS = ["proposal-added", "action-approval-needed"];
 var TITLE = "Suveren";
@@ -4273,6 +4493,33 @@ app.get("/auth/oauth/:integrationId/health", authGuard, async (req, res) => {
 });
 app.get("/events", requireAllowedHost, requireAuthQueryOrHeader(vault), createEventsHandler());
 app.use("/internal", jsonParser, createInternalEventsRouter(() => internalSecret2, lockExpiredSession, lockAsKeyMismatch, lockAsTlsMismatch));
+app.use("/internal", jsonParser, createInternalMandateRouter(() => internalSecret2, () => ({
+  user: vault.getSessionUser(),
+  as: async (method, path, body) => {
+    const cookie = vault.getSpCookie();
+    if (!cookie) return { status: 401, body: { error: "not signed in" } };
+    const pin = readPairing(DATA_DIR);
+    try {
+      const { res } = await fetchAs(
+        `${SP_URL}${path}`,
+        {
+          method,
+          headers: { Cookie: cookie, ...body !== void 0 ? { "Content-Type": "application/json" } : {} },
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: AbortSignal.timeout(15e3)
+        },
+        { enforce: resolvePinTls(DATA_DIR), pinnedSpkiHex: pin && pin.asUrl === SP_URL ? pin.tlsSpkiPinHex : void 0 }
+      );
+      if (res.status === 401 && vault.isUnlocked()) lockExpiredSession();
+      return { status: res.status, body: await res.json().catch(() => ({})) };
+    } catch (err) {
+      if (err instanceof AsTlsMismatchError) lockAsTlsMismatch();
+      throw err;
+    }
+  },
+  encrypt: encryptIntentForRecipients,
+  deliverGateContent: (args) => pushGateContent(args)
+})));
 app.use("/vault", jsonParser, authGuard, createVaultRouter(vault));
 app.use("/ai", jsonParser, authGuard, createAIRouter(vault));
 app.use("/ai-prompts", jsonParser, authGuard, createAIPromptsRouter());
@@ -4466,6 +4713,14 @@ app.post("/gate-content", jsonParser, authGuard, async (req, res) => {
     res.status(500).json({ error: "Failed to forward gate content to MCP server" });
   }
 });
+app.get("/tool-display", authGuard, async (_req, res) => {
+  try {
+    res.json(await getToolDisplay());
+  } catch (err) {
+    console.error("[Control Plane] tool-display error:", err);
+    res.status(502).json({ error: "MCP server unavailable" });
+  }
+});
 app.post("/resync-gates", authGuard, async (_req, res) => {
   try {
     const data = await resyncGates();

package/dist/mcp-server/http.mjs

@@ -2984,7 +2984,7 @@ function createGatedToolHandler(tool, integrationManager2, state2) {
   const gateable = !!tool.gating?.profile && tool.gating.category !== "disabled";
   const inner = async (args) => {
     const normalized = normalizeIncomingArgs(tool, args);
-    const refusal = gateable ? integrationManager2.precheckBuiltin?.(tool, normalized) : null;
+    const refusal = gateable ? await integrationManager2.precheckBuiltin?.(tool, normalized) : null;
     if (refusal) return { content: [{ type: "text", text: refusal }], isError: true };
     return gated(normalized);
   };
@@ -5238,6 +5238,28 @@ var IntegrationManager = class {
     console.error(`[IntegrationManager] Built-in ${def.id}: ${tools.length} tool(s) under profile ${def.profile}`);
     this.onToolsChanged?.();
   }
+  /** The built-in groups, for the mandate picker — never part of the connector status list. */
+  getBuiltins() {
+    return Array.from(this.builtins.values()).map(({ def }) => ({
+      id: def.id,
+      name: def.name,
+      description: def.description ?? "",
+      profile: def.profile,
+      available: !def.simulationOnly || isSimulationMode()
+    }));
+  }
+  /**
+   * What the approval screen needs to show a proposal for each tool: its argument
+   * schema (labels from the descriptions) and the optional approvalView hints.
+   * Keyed by the namespaced tool name a proposal carries.
+   */
+  getToolDisplay() {
+    const out = {};
+    for (const t of this.getAllTools()) {
+      out[t.namespacedName] = { inputSchema: t.inputSchema, ...t.gating?.approvalView ? { approvalView: t.gating.approvalView } : {} };
+    }
+    return out;
+  }
   /** Whether `id` names a built-in (in-process) integration. */
   isBuiltin(id) {
     return this.builtins.has(id);
@@ -5256,14 +5278,14 @@ var IntegrationManager = class {
    * no ticket): `simulationOnly` outside simulation mode, then the tool's `validate`.
    * Null for connector tools and for calls that may proceed.
    */
-  precheckBuiltin(tool, args) {
+  async precheckBuiltin(tool, args) {
     const builtin = this.builtins.get(tool.integrationId);
     if (!builtin) return null;
     if (builtin.def.simulationOnly && !isSimulationMode()) {
       return `Refused: "${tool.namespacedName}" is not available. No ticket was requested.`;
     }
     const def = builtin.def.tools.find((t) => t.name === tool.originalName);
-    const refusal = def?.validate?.(args);
+    const refusal = await def?.validate?.(args);
     return refusal ? `Refused: ${refusal} No ticket was requested.` : null;
   }
   /**
@@ -5474,7 +5496,8 @@ var IntegrationManager = class {
           readGovernance: ext.readGovernance,
           readGovernanceReason: ext.readGovernanceReason,
           blockedArgs: ext.blockedArgs,
-          hideUnlessAuthorized: ext.hideUnlessAuthorized
+          hideUnlessAuthorized: ext.hideUnlessAuthorized,
+          approvalView: ext.approvalView
         };
       }
       return {
@@ -5489,7 +5512,8 @@ var IntegrationManager = class {
         blockedArgs: ext.blockedArgs,
         argEncoding: ext.argEncoding,
         argNormalization: ext.argNormalization,
-        hideUnlessAuthorized: ext.hideUnlessAuthorized
+        hideUnlessAuthorized: ext.hideUnlessAuthorized,
+        approvalView: ext.approvalView
       };
     }
     return {
@@ -5596,6 +5620,27 @@ function builtinText(text) {
   return { content: [{ type: "text", text }] };
 }
 
+// src/lib/cp-mandate.ts
+var CP_PORT2 = process.env.SUVEREN_CP_PORT ?? "3402";
+var CP_BASE2 = process.env.SUVEREN_CP_INTERNAL_URL ?? `http://127.0.0.1:${CP_PORT2}`;
+async function controlPlaneMandate(dryRun, request) {
+  const secret = process.env.SUVEREN_INTERNAL_SECRET ?? "";
+  if (!secret) return { ok: false, message: "the gateway is not fully started (no control plane connection)." };
+  try {
+    const res = await fetch(`${CP_BASE2}/internal/mandate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Internal-Secret": secret },
+      body: JSON.stringify({ dryRun, request }),
+      signal: AbortSignal.timeout(3e4)
+    });
+    const body = await res.json().catch(() => ({}));
+    if (res.ok) return { ok: true, ...body };
+    return { ok: false, message: typeof body.message === "string" ? body.message : `control plane answered ${res.status}` };
+  } catch (err) {
+    return { ok: false, message: `the control plane could not be reached (${err instanceof Error ? err.message : String(err)}).` };
+  }
+}
+
 // src/lib/builtins/setup.ts
 var DELEGATION_PROFILE = "github.com/humanagencyprotocol/hap-profiles/delegation@0.1";
 function briefRefusal(args) {
@@ -5608,6 +5653,7 @@ function setupBuiltin(_deps) {
   return {
     id: "setup",
     name: "Test setup",
+    description: "Your AI proposes its own setup for a test \u2014 its agent brief and its mandates. Every proposal waits for your approval. Simulation mode only.",
     profile: DELEGATION_PROFILE,
     simulation: true,
     simulationOnly: true,
@@ -5616,7 +5662,24 @@ function setupBuiltin(_deps) {
         set_agent_brief: {
           executionMapping: {},
           staticExecution: { action_type: "brief" },
-          hideUnlessAuthorized: true
+          hideUnlessAuthorized: true,
+          approvalView: { content: { label: "New agent brief", kind: "markdown" } }
+        },
+        create_mandate: {
+          executionMapping: {},
+          staticExecution: { action_type: "mandate" },
+          hideUnlessAuthorized: true,
+          // Shown like the mandate screen: limits and scope by the profile's own names.
+          approvalView: {
+            team: { label: "Team" },
+            profile: { label: "Profile", kind: "profile" },
+            limits: { label: "Limits", kind: "profile-limits", profileArg: "profile" },
+            scope: { label: "Scope", kind: "profile-scope", profileArg: "profile" },
+            intent: { label: "Intent", kind: "markdown" },
+            mode: { label: "Mode" },
+            duration_hours: { label: "Valid for (hours)" },
+            title: { label: "Title" }
+          }
         }
       }
     },
@@ -5645,10 +5708,56 @@ function setupBuiltin(_deps) {
             `Agent brief replaced (${Buffer.byteLength(args.content, "utf-8")} bytes). It applies from the next agent session.`
           );
         }
+      },
+      {
+        name: "create_mandate",
+        description: "Simulation mode only: propose a new mandate for the person running this gateway \u2014 the authority another tool needs (e.g. sales quotes up to a value). A person approves or rejects the proposal; only after approval is the mandate created, exactly as if they had signed it on the mandate screen. Checked against the profile before the proposal: unknown limits, a mode the profile does not allow, or a team where the person may not give this mandate are refused at once. Create only.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            team: { type: "string", description: "Team name or id. Omit for the personal workspace." },
+            profile: { type: "string", description: 'Profile, e.g. "sales" (newest version) or a full profile id.' },
+            limits: { type: "object", description: "The limits (bounds) by field name, as the profile defines them." },
+            scope: { type: "object", description: "The scope (context) by field name, as the profile defines it." },
+            intent: { type: "string", description: "Why, goal and watch-outs \u2014 signed with the mandate (at most 2000 characters)." },
+            mode: { type: "string", enum: ["review", "automatic"], description: "review = each action needs approval; automatic = within the limits." },
+            duration_hours: { type: "number", description: "How long the mandate is valid, in hours. Omit for the profile default." },
+            title: { type: "string", description: "A short name for the mandate." },
+            receipt_id: {
+              type: "string",
+              description: "Authorization reference for this call, set by the governing gateway \u2014 agents do not set this."
+            }
+          },
+          required: ["profile", "limits", "intent", "mode"]
+        },
+        validate: async (args) => {
+          const check = await controlPlaneMandate(true, mandateRequest(args));
+          return check.ok ? void 0 : check.message;
+        },
+        handler: async (args) => {
+          if (!isSimulationMode()) return { ...builtinText("Refused: not available outside simulation mode."), isError: true };
+          const r = await controlPlaneMandate(false, mandateRequest(args));
+          if (!r.ok) return { ...builtinText(`Refused: ${r.message}`), isError: true };
+          return builtinText(
+            `Mandate created: ${r.authorizationId} \u2014 profile ${r.profileId}, ${r.groupName}, mode ${r.mode}, valid for ${Math.round((r.ttlSeconds ?? 0) / 3600)} h. It is active now.`
+          );
+        }
       }
     ]
   };
 }
+function mandateRequest(args) {
+  return {
+    team: typeof args.team === "string" && args.team.trim() ? args.team.trim() : void 0,
+    profile: args.profile,
+    limits: args.limits,
+    scope: args.scope,
+    intent: args.intent,
+    mode: args.mode,
+    durationHours: args.duration_hours,
+    title: args.title
+  };
+}
 
 // src/lib/builtins/index.ts
 var BUILTIN_FACTORIES = [setupBuiltin];
@@ -6134,9 +6243,15 @@ app.get("/health", (_req, res) => {
     activeSessions: activeSessions.size,
     storedGates: state.gateStore.getAll().length,
     serviceCredentials: Array.from(serviceCredentials.keys()),
-    integrations: integrationManager.getStatus(integrationRegistry.getAll())
+    integrations: integrationManager.getStatus(integrationRegistry.getAll()),
+    // The gateway's own tool groups (built-ins) — not connectors; the mandate
+    // picker offers them so a person can give a mandate for them.
+    builtins: integrationManager.getBuiltins()
   });
 });
+app.get("/internal/tool-display", internalOnly, (_req, res) => {
+  res.json({ tools: integrationManager.getToolDisplay() });
+});
 app.get("/internal/gate-content", internalOnly, (req, res) => {
   const path = req.query.path;
   const gates = state.gateStore.getAll();