@sigrun/ext-mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,67 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Security
+- **stdio MCP servers receive an allowlisted environment instead of sigrun's
+  process environment.** `SIGRUN_API_TOKEN` and provider keys were inherited
+  by every spawned stdio server; they now see only the variables their
+  declaration names plus a minimal base. Previously published `0.2.0` is
+  affected; `0.2.1` is the first release with the fix.
+
+### Changed
+- **Upgrade behavior:** catalog servers now default to `credentials: "user"`.
+  Existing installs that rely on one system-wide server must explicitly
+  select `credentials: "shared"` and provide `sharedAuthority`. Shared MCP
+  servers hand every permitted user's agent the admin's credential for that
+  service.
+
+### Fixed
+- Per-user tool publication is declared even with an empty or shared-only
+  catalog, so lifecycle activation and prompt rendering no longer fail when
+  there are no personal catalog servers. Because the declaration is
+  unconditional, core's boot sweep now writes `sigrun.mcp@<owner>` into every
+  owned conversation's selection on the first boot after upgrading, even with
+  no `mcp.json` or `userServers: "none"`. That is a one-time durable write:
+  the name resolves to nothing while no tools are published, so nothing
+  changes for the conversation, and later boots report zero.
+- Catalog enablement now mounts through `surfaces.settings` and uses core's
+  actual flat settings shape: each toggle and changed key is the bare server
+  name. Shared-authority help is punctuated and guarded against missing
+  programmatic input.
+- Prompt sections resolve the conversation owner through the harness's
+  committed-read surface instead of the server-bound identity bridge, so
+  harness-only boots cannot hang while preparing a request.
+
+### Added
+- User-supplied MCP servers in per-user settings, gated by `userServers:
+  "none" | "remote" | "all"` and validated with the operator config parser.
+  Tools publish as `u_<server>/<tool>`; live policy changes reconcile every
+  active user. The `all` mode also permits URL servers, but reports
+  user-supplied stdio as a named configuration error because the host's
+  static user-service contract cannot launch it safely.
+- Per-user OAuth start/complete extension routes with ten-minute in-memory
+  PKCE state scoped by user and server. Completion stores the raw access
+  token in the caller's scoped secrets; the CLI refuses per-user servers.
+- Token storage retires and reconnects the caller's catalog connection.
+  Core owns the process lifecycle: a still-live child retains its original
+  environment until idle-stop or exit because the host contract cannot force
+  a relaunch.
+- MCP catalog entries default to per-user credentials, with lazy per-user
+  stdio services, scoped token injection, remote connections, and tools
+  published only for their owner. Opt-in availability and per-user settings
+  control enablement; disabling removes tools and drains active calls.
+- Shared entries require `sharedAuthority`, retain system-tool behavior,
+  and enforce their optional user allowlist and enablement at call time.
+  Prompt sections list only servers available to the calling user.
+
+### Security
+- Stdio servers no longer inherit sigrun's environment. They are spawned
+  with an allowlist (`PATH`, `HOME`, `TMPDIR`, `LANG`, `LC_*`, `TZ`,
+  `TERM`, `USER`, `LOGNAME`, `SHELL`, `NPM_CONFIG_CACHE`,
+  `SSH_AUTH_SOCK`) plus their configured `env` and stored token.
+  Previously every server could read `SIGRUN_API_TOKEN`,
+  `SIGRUN_PROXY_SECRET` and provider keys. A server that relied on an
+  inherited variable must now list it in its `env`.
 
 ## [0.2.0] - 2026-10-22
 ### Added

package/README.md

@@ -33,8 +33,25 @@ bare user install falls back to `~/.config/sigrun/mcp.json`; the
   `endpoint` event + message POSTs) is adopted automatically, so no adapter
   process is needed.
 - `headers` (remote) — extra request headers (auth etc.), sent on every
-  request.
-- `env` (stdio) — extra environment variables for the child process.
+  request. For per-user servers, configured `Authorization` is removed;
+  only that user's scoped token supplies it.
+- `env` (stdio) — extra environment variables for the child process. For
+  per-user servers, configured `MCP_ACCESS_TOKEN` is removed; only that
+  user's scoped token supplies it.
+- `credentials` — `"user"` (default) or `"shared"`. User-credential servers
+  start per user in the host's service jail; remote user servers connect
+  with the user's scoped token. Existing installs needing one system-wide
+  server must explicitly select `"shared"`.
+- `sharedAuthority` — required, non-empty one-line reason when
+  `credentials` is `"shared"`. Shared MCP servers hand every permitted
+  user's agent the admin's credential for that service; the settings
+  section displays this reason and warning beside the server.
+- `users` — optional string allowlist for a shared server. Only those
+  users may call its tools; this field is invalid for user-credential
+  servers. Ownerless calls fail closed.
+- `availability` — `"all"` (default) or `"opt-in"`. The per-user settings
+  section stores each server's enablement as a flat boolean keyed by its
+  bare server name. `"all"` starts enabled; `"opt-in"` starts disabled.
 - `enabled` (default `true`) / `disabled` — skip the server entirely. Set one,
   never both: a server that is simultaneously on and off is a config error and
   fails loudly.
@@ -46,9 +63,47 @@ bare user install falls back to `~/.config/sigrun/mcp.json`; the
 - `toolExposure` — per-tool overrides of `exposure`: an object mapping tool
   names (exact) or `*`-globs (e.g. `"get-*"`) to exposure words. An exact name
   always wins; among matching patterns the FIRST one in config order wins.
-- `oauth` (stdio) — the authorization-code (PKCE) flow block; see
-  `sigrun-ext-mcp oauth <server>` (the CLI mints and stores a token; the spawn
-  injects it).
+- `oauth` (stdio) — the authorization-code (PKCE) flow block. Shared servers
+  use `sigrun-ext-mcp oauth <server>` and the file token store. Per-user
+  servers use `POST /v1/ext/sigrun-mcp/oauth/<server>/start`, then
+  `POST /v1/ext/sigrun-mcp/oauth/<server>/complete` with
+  `{ "redirectedUrl": "<full redirected URL>" }`; the CLI refuses these
+  servers so their credentials cannot enter the shared store.
+
+Per-user PKCE state stays in memory for ten minutes and is scoped to the
+authenticated user and server. Completion stores only the raw access token in
+that user's `token:<server>` secret. It then retires and reconnects that
+user's catalog connection. Core owns the process lifecycle: releasing the last
+handle arms idle-stop, so a still-live child keeps its original environment
+until that timer fires or it crashes; the extension cannot force a relaunch
+through the host contract. An already idle-stopped server launches fresh on
+the next activation and reads the new token immediately.
+
+`userServers` is the separate admin policy for user-supplied servers:
+`"none"` (default), `"remote"`, or `"all"`. It is distinct from the admin
+catalog's `credentials` and `availability` fields above. Catalog names
+starting `u_` are reserved for those user-supplied servers and rejected.
+
+When enabled, the **Your MCP servers** settings section accepts a JSON object
+under the `servers` key. Entries use the same validation rules as `mcp.json`;
+a user server name may not start with `u_`. Its tools publish only to that
+user as `u_<server>/<tool>`. `"remote"` permits URL servers and ignores stdio;
+`"all"` permits URL servers too. A live policy change reconciles every active
+user, retiring disallowed connections and removing their tools without a
+restart. Lifecycle events re-read the policy from `mcp.json`, since this
+operator file is not part of core's settings document. The contributed
+settings sections are selected at extension load: changing `none` to an
+enabled policy needs a restart to add the editor, and changing to `none`
+needs a restart to remove it; connection gating itself takes effect at the
+next lifecycle event. A catalog server literally named `servers` is rejected
+because it would shadow this settings namespace.
+
+**Named limitation — `all` and user-supplied stdio:** sigrun declares per-user
+services statically at load and passes no server name to `UserService.start`.
+Consequently a dynamic, named user-supplied stdio service cannot be launched.
+Under `"all"`, such an entry is reported as a configuration error naming the
+server; its command is never spawned in sigrun's process, and no tools are
+published. `"all"` does **not** make user-supplied stdio functional.
 
 ## Exposure: how tools reach callers
 

package/dist/cli.js

@@ -71,6 +71,10 @@ export async function runCli(argv, io = { stdout: process.stdout, stderr: proces
         io.stderr.write(`error: no server named "${parsed.server}" in the MCP config\n`);
         return 1;
     }
+    if (server.credentials !== "shared") {
+        io.stderr.write(`error: server "${parsed.server}" uses per-user credentials; use POST /v1/ext/sigrun-mcp/oauth/${parsed.server}/start instead\n`);
+        return 1;
+    }
     if (!isStdioServer(server) || server.oauth === undefined) {
         io.stderr.write(`error: server "${parsed.server}" has no oauth block in the MCP config\n`);
         return 1;

package/dist/client.d.ts

@@ -33,10 +33,20 @@ export interface McpClient {
     /** Tear the connection down (idempotent). */
     close(): void;
 }
+/** The byte streams of a core-launched per-user service. */
+export interface McpServiceHandle {
+    readonly stdin: WritableStream<Uint8Array>;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly exited: Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    release(): void;
+}
 /**
  * Spawn/connect one configured MCP server (stdio or remote by config
  * shape). Throws on spawn/connect failure or a failed handshake —
  * per-server isolation is the CALLER's policy (the extension connects all
  * servers with `.catch` per server).
  */
-export declare function connectMcpServer(name: string, config: McpServerConfig): Promise<McpClient>;
+export declare function connectMcpServer(name: string, config: McpServerConfig, handle?: McpServiceHandle): Promise<McpClient>;

package/dist/client.js

@@ -26,7 +26,7 @@
  * transport (per-server isolation: the next request gets a fresh chance).
  */
 import { spawn } from "node:child_process";
-import { spawnEnvWithToken } from "./tokens.js";
+import { serverSpawnEnv } from "./spawn-env.js";
 import { DEFAULT_TIMEOUT_SECONDS } from "./config.js";
 const MCP_PROTOCOL_VERSION = "2025-06-18";
 function isRecord(value) {
@@ -183,9 +183,6 @@ class McpEngine {
         this.handleDeath(new Error("mcp client closed"));
     }
 }
-// ---------------------------------------------------------------------------
-// stdio transport (the original): today's behavior, moved verbatim in shape.
-// ---------------------------------------------------------------------------
 /** One connected stdio MCP server: a live child process speaking JSON-RPC. */
 class StdioTransport {
     #engine;
@@ -267,6 +264,98 @@ class StdioTransport {
         this.#engine.handleDeath(new Error("mcp client closed"));
     }
 }
+/** MCP framing over a core-owned service's Web-standard streams. The host
+ * owns the jail and process; this transport owns only its stream handle. */
+class HandleTransport {
+    #engine;
+    #handle;
+    #writer;
+    #closed = false;
+    #released = false;
+    #read;
+    constructor(name, handle) {
+        this.#handle = handle;
+        this.#engine = new McpEngine(name, this);
+        this.#writer = handle.stdin.getWriter();
+        this.#read = this.#readStdout(name);
+        void handle.exited.then(({ code, signal }) => {
+            this.#die(new Error(`mcp service exited (code ${code ?? "?"}, signal ${signal ?? "?"})`));
+        });
+    }
+    get engine() {
+        return this.#engine;
+    }
+    async #readStdout(name) {
+        const reader = this.#handle.stdout.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                for (;;) {
+                    const newline = buffer.indexOf("\n");
+                    if (newline < 0)
+                        break;
+                    const line = buffer.slice(0, newline).trim();
+                    buffer = buffer.slice(newline + 1);
+                    if (line === "")
+                        continue;
+                    try {
+                        this.#engine.handleFrame(JSON.parse(line));
+                    }
+                    catch {
+                        // A non-JSON line is server chatter, not a protocol frame.
+                    }
+                }
+            }
+            if (!this.#closed) {
+                this.#die(new Error(`mcp service "${name}" stdout ended`));
+            }
+        }
+        catch (cause) {
+            if (!this.#closed) {
+                this.#die(cause instanceof Error
+                    ? cause
+                    : new Error(`mcp service "${name}" stream failed`));
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    #die(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#engine.handleDeath(error);
+        this.#release();
+    }
+    #release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        this.#handle.release();
+    }
+    send(frame) {
+        if (this.#closed) {
+            return Promise.reject(new Error("mcp service transport is closed"));
+        }
+        return this.#writer.write(new TextEncoder().encode(JSON.stringify(frame) + "\n"));
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        void this.#writer.close().catch((cause) => {
+            console.warn(`mcp service stdin close failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        });
+        this.#engine.handleDeath(new Error("mcp client closed"));
+        this.#release();
+    }
+}
 // ---------------------------------------------------------------------------
 // Remote transport: streamable HTTP with a legacy-SSE fallback.
 // ---------------------------------------------------------------------------
@@ -659,16 +748,24 @@ class HttpTransport {
  * per-server isolation is the CALLER's policy (the extension connects all
  * servers with `.catch` per server).
  */
-export async function connectMcpServer(name, config) {
+export async function connectMcpServer(name, config, handle) {
     let engine;
-    if ("url" in config) {
+    if (handle !== undefined) {
+        if (!("command" in config)) {
+            handle.release();
+            throw new Error(`mcp server "${name}" remote transport cannot use a service handle`);
+        }
+        const transport = new HandleTransport(name, handle);
+        engine = transport.engine;
+    }
+    else if ("url" in config) {
         const transport = new HttpTransport(name, config);
         engine = transport.engine;
     }
     else {
-        // Token injection (ruling 3): a server with an oauth block AND a stored
-        // token gets it as MCP_ACCESS_TOKEN, merged over the server's own env.
-        const env = { ...process.env, ...spawnEnvWithToken(name, config) };
+        // Never sigrun's own environment: an allowlist, the server's config
+        // env, then its stored token as MCP_ACCESS_TOKEN (ruling 3).
+        const env = serverSpawnEnv(name, config);
         const transport = new StdioTransport(name, config.command, config.args, env);
         engine = transport.engine;
     }

package/dist/config.d.ts

@@ -34,8 +34,20 @@ export declare function resolveToolExposure(server: McpServerConfig, toolName: s
  * `disabled: true` both skip it (parse-time validation rejects
  * contradictions, so either false simply means off). */
 export declare function serverEnabled(server: McpServerConfig): boolean;
+/** Who supplies the server's authority and owns its connection lifecycle. */
+export type McpCredentials = "user" | "shared";
+/** Whether every user starts enabled or must explicitly opt in. */
+export type McpAvailability = "all" | "opt-in";
 /** Fields every server variant carries regardless of transport. */
 interface McpServerCommon {
+    /** Per-user jailed connections by default; shared authority is opt-in. */
+    readonly credentials?: McpCredentials;
+    /** Required for shared entries: why lending this authority is acceptable. */
+    readonly sharedAuthority?: string;
+    /** Optional allowlist for a shared entry; rejected for user credentials. */
+    readonly users?: readonly string[];
+    /** Absent user settings mean enabled for all, disabled for opt-in. */
+    readonly availability?: McpAvailability;
     /** Skip this server entirely (default false). */
     readonly disabled?: boolean;
     /** Skip this server entirely (default true; contradicts `disabled`). */
@@ -85,9 +97,11 @@ export interface McpOAuthConfig {
     /** PKCE method (optional; only "S256" is implemented — and always used). */
     readonly codeChallengeMethod?: string;
 }
+export type UserServersMode = "none" | "remote" | "all";
 /** The parsed `mcp.json` body. */
 export interface McpConfig {
     readonly servers: Readonly<Record<string, McpServerConfig>>;
+    readonly userServers?: UserServersMode;
 }
 /** The env override the config store reads. */
 export declare const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";

package/dist/config.js

@@ -128,12 +128,22 @@ export function parseMcpConfig(text, source) {
     if (!isRecord(parsed)) {
         throw new Error(`mcp config ${source} must be a JSON object`);
     }
+    const userServers = parsed.userServers ?? "none";
+    if (userServers !== "none" && userServers !== "remote" && userServers !== "all") {
+        throw new Error(`mcp config ${source}: userServers must be one of "none", "remote", "all"`);
+    }
     const servers = {};
     const rawServers = parsed.servers;
     if (!isRecord(rawServers)) {
         throw new Error(`mcp config ${source} must have a "servers" object mapping names to server entries`);
     }
     for (const [name, entry] of Object.entries(rawServers)) {
+        if (name === "servers") {
+            throw new Error(`mcp config ${source}: server "servers" uses the reserved user settings namespace`);
+        }
+        if (name.startsWith("u_")) {
+            throw new Error(`mcp config ${source}: server "${name}" uses the reserved "u_" prefix`);
+        }
         if (!isRecord(entry)) {
             throw new Error(`mcp config ${source}: server "${name}" must be an object`);
         }
@@ -168,6 +178,28 @@ export function parseMcpConfig(text, source) {
                 Object.values(entry.env).some((v) => typeof v !== "string"))) {
             throw new Error(`mcp config ${source}: server "${name}" env must map strings to strings`);
         }
+        const credentials = (entry.credentials ?? "user");
+        if (credentials !== "user" && credentials !== "shared") {
+            throw new Error(`mcp config ${source}: server "${name}" credentials must be "user" or "shared"`);
+        }
+        if (credentials === "shared" &&
+            (typeof entry.sharedAuthority !== "string" ||
+                entry.sharedAuthority.trim() === "")) {
+            throw new Error(`mcp config ${source}: server "${name}" requires a non-empty sharedAuthority when credentials are "shared"`);
+        }
+        if (entry.users !== undefined) {
+            if (credentials !== "shared") {
+                throw new Error(`mcp config ${source}: server "${name}" users is only valid with credentials "shared"`);
+            }
+            if (!Array.isArray(entry.users) ||
+                entry.users.some((user) => typeof user !== "string" || user.trim() === "")) {
+                throw new Error(`mcp config ${source}: server "${name}" users must be a string[] of non-empty users`);
+            }
+        }
+        const availability = (entry.availability ?? "all");
+        if (availability !== "all" && availability !== "opt-in") {
+            throw new Error(`mcp config ${source}: server "${name}" availability must be "all" or "opt-in"`);
+        }
         if (entry.disabled !== undefined && typeof entry.disabled !== "boolean") {
             throw new Error(`mcp config ${source}: server "${name}" disabled must be a boolean`);
         }
@@ -204,6 +236,19 @@ export function parseMcpConfig(text, source) {
         const oauth = entry.oauth === undefined
             ? undefined
             : parseOauthEntry(entry.oauth, source, name);
+        const catalog = {
+            // Preserve the pre-catalog serialized shape when both fields are
+            // absent. Consumers use nullish defaults, so omitted and explicit
+            // default values are equivalent without changing legacy fixtures.
+            ...(entry.credentials === undefined ? {} : { credentials }),
+            ...(entry.availability === undefined ? {} : { availability }),
+            ...(entry.sharedAuthority === undefined
+                ? {}
+                : { sharedAuthority: entry.sharedAuthority }),
+            ...(entry.users === undefined
+                ? {}
+                : { users: entry.users }),
+        };
         // The common optionals first, then the transport arm's own fields —
         // the union stays discriminable by "command" vs "url" presence.
         servers[name] = hasUrl
@@ -217,6 +262,7 @@ export function parseMcpConfig(text, source) {
                 ...(exposure === undefined ? {} : { exposure }),
                 ...(toolExposure === undefined ? {} : { toolExposure }),
                 ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
+                ...catalog,
             }
             : {
                 command: entry.command,
@@ -230,9 +276,10 @@ export function parseMcpConfig(text, source) {
                 ...(toolExposure === undefined ? {} : { toolExposure }),
                 ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
                 ...(oauth === undefined ? {} : { oauth }),
+                ...catalog,
             };
     }
-    return { servers };
+    return { servers, userServers };
 }
 /** Parse one server's oauth block. Fail-loud on a wrong shape: a
  * half-configured block is a config error, not a silently-ignored field. */

package/dist/extension.d.ts

@@ -1,51 +1,32 @@
-/**
- * The MCP extension (sigrun-ext-mcp): registers every tool discovered on
- * the configured MCP servers as a pi-durable tool named
- * `<server>/<toolname>` (ruling 4).
- *
- * Contract (sigrun's src/harness/loader.ts): the package default-exports a
- * FACTORY TAKING NO ARGUMENTS, returning `{ extension }`. The loader calls
- * it synchronously at boot, before `Harness.open` reads the registry — so
- * the factory returns immediately and the async connect/discover work lands
- * through a LIVE tools array (the registry re-reads `extension.tools` on
- * every snapshot, so tools discovered after install appear in the harness
- * without a reinstall).
- *
- * Lifecycle (ruling 5): servers spawn eagerly at factory time (a server is
- * a long-lived stdio process; lazy-at-first-use buys nothing and complicates
- * discovery visibility). Each server is ISOLATED: a spawn or handshake or
- * discovery failure quarantines just that server (warned, contributing no
- * tools) and never affects the others. Children are killed on process exit
- * and on `wiring.close()`; there is no loader-side uninstall callback to
- * hook.
- *
- * Config (ruling 2): `mcp.json` resolved as `SIGRUN_MCP_CONFIG` env
- * override → `~/.config/sigrun/mcp.json`. Malformed config THROWS from the
- * factory (the loader's quarantine semantics take over); a missing config
- * is an empty registry (the extension installs with zero tools).
- */
+/** Catalog wiring: shared operator services remain system children, while
+ * per-user entries connect and publish through the structural sigrun host. */
 import { type Extension } from "@earendil-works/pi-durable";
-/** The extension's pi-durable registry name. */
+import { type CatalogSettingsSection, type OwnerEvent, type SigrunHost, type UserService } from "./user-servers.js";
 export declare const MCP_EXTENSION_NAME = "sigrun.mcp";
-/** What {@link createMcpExtension} returns (the loader contract: `.extension`). */
+export interface ExtensionRouteContribution {
+    readonly method: "POST";
+    readonly path: string;
+    readonly auth: "user";
+    handler(request: Request, ctx: {
+        readonly principal?: {
+            readonly user?: string;
+        };
+        readonly host: SigrunHost;
+    }): Promise<Response>;
+}
 export interface McpWiring {
-    /** The extension to install into the harness registry. */
     readonly extension: Extension;
-    /**
-     * Kill every connected MCP server child process (idempotent). Called on
-     * process exit automatically; hosts may call it on harness shutdown.
-     */
-    close(): void;
-    /**
-     * Resolves when every enabled server has connected (and discovered its
-     * tools) or failed (isolated). Hosts that want tools present before
-     * `Harness.open` reads the registry await this; the loader does not.
-     */
+    readonly perUserTools: boolean;
+    readonly routes: readonly ExtensionRouteContribution[];
+    readonly userServices: readonly UserService[];
+    readonly surfaces: {
+        readonly settings: readonly CatalogSettingsSection[];
+    };
+    conversationCreated(event: OwnerEvent): Promise<void>;
+    runSettled(event: OwnerEvent): Promise<void>;
+    onSettingsChanged(keys: readonly string[], user?: string): Promise<void>;
+    /** Stop system clients immediately; per-user clients drain in-flight calls. */
+    close(): Promise<void>;
     readonly ready: Promise<void>;
 }
-/**
- * The extension factory (the loader contract: no arguments; config resolves
- * from the package context — the `SIGRUN_MCP_CONFIG` override or the sigrun
- * config dir).
- */
-export declare function createMcpExtension(): McpWiring;
+export declare function createMcpExtension(host: SigrunHost): McpWiring;