@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/mcp-mounts.d.ts

@@ -0,0 +1,239 @@
+/**
+ * mcp-mounts — aggregate external MCP tool handler bundles onto the
+ * ggui `/mcp` surface so one session can see ggui-native tools (e.g.
+ * `ggui_push`) AND mounted tools (e.g. `tasks_*`) through a single
+ * MCP connection.
+ *
+ * Scope lock: a **mount** is a named bundle of `SharedHandler`
+ * instances. That's the same runtime contract ggui's own default
+ * handlers already satisfy — no proxy, no in-memory MCP wire, no
+ * extra registry. A fixture (or any host package) that wants to
+ * expose its tools on the OSS path builds `SharedHandler[]` against
+ * the same seams ggui's native handlers use, wraps them in a mount,
+ * and passes the mount to {@link CreateGguiServerOptions.mcpMounts}.
+ *
+ * The narrower "proxy an external MCP server whose source you can't
+ * modify" path (connector registry + `tools/list` forwarding) is
+ * deliberately NOT handled here — it is a separate seam. The bundle
+ * seam is the smallest honest shape for in-process mounts: it reuses
+ * the exact same handler interface, so collision checks,
+ * `buildMcpServer` registration, `toolCount`, telemetry, and logging
+ * all Just Work.
+ */
+import type { ZodRawShape } from 'zod';
+import type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
+import type { WiredActionContext, WiredActionRouter } from './session-channel.js';
+/**
+ * Runtime ctx the mount-router hands the mount handler. Structurally a
+ * superset of `HandlerContext` (so the mount's `handler(input, ctx)`
+ * signature stays unchanged) PLUS the wired-action-only fields from
+ * {@link WiredActionContext}.
+ *
+ * Why the type is exported: TS-authored mount tools that want to read
+ * `ctx.sendPropsUpdate` / `ctx.stackItemId` import this and narrow their
+ * `handler` parameter (e.g. `async handler(input, ctx) { const wired =
+ * ctx as WiredMountContext; … }`). JS-authored mounts (.mjs) read the
+ * fields structurally — they're present on the runtime object whether
+ * or not the static type knows about them.
+ *
+ * The static `SharedHandler.handler` signature deliberately stays
+ * narrow on `HandlerContext`. Widening that type would force every
+ * shared handler (ggui-native + mounted) to acknowledge a wired-only
+ * surface, even handlers that never run through the wired-action path
+ * (e.g. `ggui_push`, blueprint search). The structural superset here
+ * keeps the canonical contract narrow without sacrificing access for
+ * mount tools that opt in.
+ */
+/**
+ * Intersection (not interface-extension) because `HandlerContext` declares
+ * `sessionId?` / `stackItemId?` as optional — the canonical context shape any
+ * handler may see — whereas `WiredActionContext` declares them as required
+ * (the wired-action dispatcher always knows the active session + stack
+ * frame at invocation time). Interface-extends rejects "narrowing
+ * optional → required" via TS2320 ("cannot simultaneously extend"), but
+ * an intersection composes the two perfectly: optional ∧ required ≡ required.
+ *
+ * Surface for consumers stays identical — a TS-authored mount that types
+ * its `handler` parameter as `WiredMountContext` reads `sessionId: string`
+ * + `stackItemId: string` (no `| undefined`) + every `HandlerContext` field
+ * (`appId`, `requestId`, optional `apiKeyHash`).
+ */
+export type WiredMountContext = Omit<HandlerContext, 'sessionId' | 'stackItemId'> & WiredActionContext;
+/**
+ * One named bundle of tool handlers the server should aggregate onto
+ * its MCP surface.
+ *
+ * `name` is diagnostic-only — it shows up in collision-error messages
+ * and composition telemetry so an operator running `ggui serve` with
+ * three mounts can tell which one is misconfigured. It does NOT appear
+ * on the wire; tool names stay whatever each handler declares.
+ */
+export interface McpServerMount {
+    /**
+     * Human-readable mount identifier. Surfaced in collision errors and
+     * `server.composed` telemetry. No uniqueness constraint across mounts
+     * (two mounts named `"tasks"` compose fine as long as their tool-name
+     * sets don't collide).
+     */
+    readonly name: string;
+    /**
+     * Tool handler bundle. Each entry is a `SharedHandler` — the same
+     * shape ggui-native handlers (blueprint family, session-mutations,
+     * threads) already use. The server calls {@link SharedHandler.handler}
+     * through `buildMcpServer`'s regular registration path; validation,
+     * logging, and output-schema parsing all happen uniformly.
+     */
+    readonly handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+}
+/**
+ * Branded HTTP path for an isolated MCP service. Mint one from a
+ * raw string via {@link validateServicePath}.
+ */
+export type ServicePath = string & {
+    readonly __brand: 'ServicePath';
+};
+/**
+ * Validate + brand a service HTTP path. Throws on malformed input or
+ * collision with a reserved built-in route.
+ *
+ * Rules:
+ * - Must start with `/`.
+ * - May contain letters, digits, `-`, `_`, and `/` (no whitespace,
+ *   no `.`, no path traversal).
+ * - Must not end with `/` (prevents trailing-slash variant collisions).
+ * - Must not equal a reserved built-in path (`/mcp`, `/protocol`, ...).
+ */
+export declare function validateServicePath(p: string): ServicePath;
+/**
+ * One isolated MCP server mounted at its own HTTP path. Unlike a
+ * {@link McpServerMount} (which contributes tools to the shared
+ * audience-filtered routes), a service is a complete, self-contained
+ * MCP server with its own tool namespace.
+ *
+ * Use a **service** when the handler set is conceptually a distinct
+ * MCP server (`mcp.ggui.ai/docs`, `mcp.ggui.ai/playground/todos`).
+ * Use a **mount** when the handlers should appear alongside
+ * ggui-native tools on the shared `/mcp` surface (fixtures, external
+ * MCPs aggregated for one session's view).
+ *
+ * Why two concepts and not one: audience tags carry caller-class
+ * semantics (`agent` vs `runtime`) that don't map 1:1 to URL paths
+ * — agent + runtime both live on `/mcp` today. Collapsing audience
+ * and path into a single "mount at path" model would lose that
+ * caller-class distinction. Mounts and services are honest about the
+ * two different things the framework actually does.
+ *
+ * Compose-time invariants (validated by {@link validateMcpServices}):
+ * - `path` passes {@link validateServicePath}.
+ * - Each handler declares a non-empty `outputSchema` (matching the
+ *   mount rule — empty schemas silently strip `structuredContent`).
+ * - Tool names are unique within a service. Cross-service collisions
+ *   ARE allowed — services are isolated namespaces; a client connects
+ *   to one path and only ever sees that path's tools.
+ * - Service handlers MUST NOT set `audience`. Services bypass
+ *   audience filtering entirely (the path IS the audience), so an
+ *   explicit tag is silently meaningless. Reject loudly.
+ * - Service paths are unique across the whole `mcpServices` array.
+ */
+export interface McpService {
+    /**
+     * Human-readable service identifier. Surfaced in validation errors
+     * and telemetry. No uniqueness constraint across services — only
+     * {@link path} must be unique.
+     */
+    readonly name: string;
+    /**
+     * HTTP path the service mounts at (e.g. `/docs`,
+     * `/playground/todos`). Validated via {@link validateServicePath} at
+     * compose time.
+     */
+    readonly path: string;
+    /**
+     * Tool handler bundle. Same shape ggui-native handlers and mount
+     * handlers use. See {@link McpService} for the service-specific
+     * rules layered on top of the canonical contract.
+     */
+    readonly handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /**
+     * When `true`, this service skips the auth chain — unauthenticated
+     * requests are let through with a synthesized identity
+     * (`{kind: 'builder'}`, `source: 'anonymous'`). Default `false`
+     * (auth required, same posture as `/mcp` / `/protocol` / `/ops`).
+     *
+     * Use for first-touch public surfaces (docs MCP, landing-agent
+     * demos) where requiring a bearer token would block the use case.
+     * Handlers that need to distinguish anonymous from authenticated
+     * traffic read `ctx` for the synthesized identity OR check the
+     * underlying `source` via the broader request context.
+     *
+     * Anonymous services SHOULD plug into the `RateLimiter` seam
+     * (per-IP + per-session keys) to prevent unbounded compute; the
+     * seam is wired the same way for authenticated and anonymous
+     * paths — this flag does not change rate-limit composition.
+     */
+    readonly anonymous?: boolean;
+}
+/**
+ * Validate every service in the array: path well-formed + non-reserved
+ * + unique across services, every handler's `outputSchema` non-empty,
+ * no `audience` tags on service handlers, no within-service tool-name
+ * collisions. Returns the input list when valid; throws with the
+ * offending service name + path embedded in the message otherwise.
+ *
+ * Cross-service tool-name collisions are deliberately NOT checked —
+ * services are isolated namespaces by design.
+ *
+ * No side effects — safe to call multiple times. Returns the input
+ * reference unchanged on the empty path.
+ */
+export declare function validateMcpServices(services: ReadonlyArray<McpService> | undefined): ReadonlyArray<McpService>;
+/**
+ * Compose a single handler list from ggui's base handlers + every
+ * mount's handlers. Throws on tool-name collision so misconfiguration
+ * surfaces at server-construction time, NOT on the first `tools/call`.
+ *
+ * Error messages intentionally mention the offending mount name so an
+ * operator with several mounts can tell which bundle introduced the
+ * collision without grepping their code.
+ *
+ * No side effects — the returned list is a fresh array even when
+ * `mounts` is empty, so callers never mutate the input reference.
+ */
+export declare function composeHandlersWithMounts(baseHandlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>, mounts: ReadonlyArray<McpServerMount> | undefined): ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+/**
+ * Build a {@link WiredActionRouter} that dispatches wired-action
+ * hits to the matching mount handler's `handler(input, ctx)`. Zero-config composition for
+ * OSS `ggui serve` — when the operator declares `ggui.json#mcpMounts`,
+ * every mounted tool automatically becomes wire-dispatchable from
+ * a generated UI's `useAction` without additional glue.
+ *
+ * Ownership + scoping:
+ *   - Only MOUNT handlers participate. ggui-native handlers
+ *     (`ggui_push`, `ggui_handshake`, etc.) are platform tools and
+ *     deliberately NOT exposed as wire-dispatchable actions — a
+ *     component that tried to dispatch `ggui_push` would bypass the
+ *     agentic-loop contract.
+ *   - Name collisions across mounts are prevented at aggregation
+ *     time by {@link composeHandlersWithMounts}, so the first-match
+ *     lookup here is safe.
+ *
+ * Context synthesis:
+ *   - Each invocation gets a fresh {@link HandlerContext} with the
+ *     caller-supplied `appId` (typically the session's appId) + a
+ *     fresh request id. Mount handlers that read from storage scope
+ *     to this appId, matching the `/mcp` ingress behavior.
+ *   - The session-channel dispatcher additionally hands a
+ *     {@link WiredActionContext}. The runtime ctx the mount handler
+ *     sees is a structural superset
+ *     ({@link WiredMountContext}) so a JS-authored mount can call
+ *     `ctx.sendPropsUpdate(ctx.stackItemId, {...})` directly. The static
+ *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
+ *     untouched — tooling that doesn't read the wired fields keeps its
+ *     existing types.
+ *
+ * Returns `null` when `mounts` is empty/absent, signaling the
+ * composer to OMIT the `wiredActionRouter` opt entirely so servers
+ * with no mounts behave as if the router did not exist.
+ */
+export declare function composeWiredActionRouterFromMounts(mounts: ReadonlyArray<McpServerMount> | undefined, resolveContext: () => HandlerContext): WiredActionRouter | null;
+//# sourceMappingURL=mcp-mounts.d.ts.map

package/dist/mcp-mounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-mounts.d.ts","sourceRoot":"","sources":["../src/mcp-mounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,aAAa,CAAC,GAC/E,kBAAkB,CAAC;AAErB;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAsBvE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAiB1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,SAAS,GAC9C,aAAa,CAAC,UAAU,CAAC,CAyC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EACpE,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,GAChD,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAyDxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACjD,cAAc,EAAE,MAAM,cAAc,GACnC,iBAAiB,GAAG,IAAI,CA2C1B"}

package/dist/mcp-mounts.js

@@ -0,0 +1,222 @@
+/**
+ * Built-in routes the multi-service mount loop must not shadow.
+ * Reserved at validation time so a typo in a host config can never
+ * silently swallow OAuth discovery / health / per-app traffic.
+ */
+const RESERVED_SERVICE_PATHS = new Set([
+    '/',
+    '/mcp',
+    '/protocol',
+    '/ops',
+    '/ws',
+    '/health',
+    '/.well-known',
+    '/oauth',
+    '/_ggui',
+    '/ggui',
+]);
+const SERVICE_PATH_REGEX = /^\/[a-zA-Z0-9_/-]+$/;
+/**
+ * Validate + brand a service HTTP path. Throws on malformed input or
+ * collision with a reserved built-in route.
+ *
+ * Rules:
+ * - Must start with `/`.
+ * - May contain letters, digits, `-`, `_`, and `/` (no whitespace,
+ *   no `.`, no path traversal).
+ * - Must not end with `/` (prevents trailing-slash variant collisions).
+ * - Must not equal a reserved built-in path (`/mcp`, `/protocol`, ...).
+ */
+export function validateServicePath(p) {
+    if (!SERVICE_PATH_REGEX.test(p)) {
+        throw new Error(`createGguiServer: mcpServices path "${p}" is malformed — must start with "/" and contain only letters, digits, "-", "_", and "/".`);
+    }
+    if (p.length > 1 && p.endsWith('/')) {
+        throw new Error(`createGguiServer: mcpServices path "${p}" must not end with "/" (use "${p.slice(0, -1)}" instead).`);
+    }
+    if (RESERVED_SERVICE_PATHS.has(p)) {
+        throw new Error(`createGguiServer: mcpServices path "${p}" collides with a reserved built-in route. Pick a distinct prefix (e.g. "/docs", "/playground/...").`);
+    }
+    return p;
+}
+/**
+ * Validate every service in the array: path well-formed + non-reserved
+ * + unique across services, every handler's `outputSchema` non-empty,
+ * no `audience` tags on service handlers, no within-service tool-name
+ * collisions. Returns the input list when valid; throws with the
+ * offending service name + path embedded in the message otherwise.
+ *
+ * Cross-service tool-name collisions are deliberately NOT checked —
+ * services are isolated namespaces by design.
+ *
+ * No side effects — safe to call multiple times. Returns the input
+ * reference unchanged on the empty path.
+ */
+export function validateMcpServices(services) {
+    if (!services || services.length === 0)
+        return services ?? [];
+    const seenPaths = new Set();
+    for (const svc of services) {
+        if (typeof svc.name !== 'string' || svc.name.length === 0) {
+            throw new Error('createGguiServer: every `mcpServices` entry must carry a non-empty string `name` (for validation-error clarity).');
+        }
+        validateServicePath(svc.path);
+        if (seenPaths.has(svc.path)) {
+            throw new Error(`createGguiServer: mcpServices path "${svc.path}" is declared by more than one service. Each service must mount at a distinct path.`);
+        }
+        seenPaths.add(svc.path);
+        const seenTools = new Set();
+        for (const h of svc.handlers) {
+            if (typeof h.outputSchema !== 'object' ||
+                h.outputSchema === null ||
+                Object.keys(h.outputSchema).length === 0) {
+                throw new Error(`createGguiServer: service "${svc.name}" handler "${h.name}" declares an empty \`outputSchema\` — this silently strips \`structuredContent\` at the MCP SDK boundary. Declare the fields the handler returns (e.g. \`outputSchema: { items: z.array(...) }\`).`);
+            }
+            if (h.audience !== undefined) {
+                throw new Error(`createGguiServer: service "${svc.name}" handler "${h.name}" sets \`audience\` (${JSON.stringify(h.audience)}). Services bypass audience filtering — the path "${svc.path}" IS the audience. Remove the \`audience\` field or move the handler to an aggregate mount.`);
+            }
+            if (seenTools.has(h.name)) {
+                throw new Error(`createGguiServer: service "${svc.name}" registers tool "${h.name}" twice. Tool names must be unique within a service (cross-service collisions ARE allowed).`);
+            }
+            seenTools.add(h.name);
+        }
+    }
+    return services;
+}
+/**
+ * Compose a single handler list from ggui's base handlers + every
+ * mount's handlers. Throws on tool-name collision so misconfiguration
+ * surfaces at server-construction time, NOT on the first `tools/call`.
+ *
+ * Error messages intentionally mention the offending mount name so an
+ * operator with several mounts can tell which bundle introduced the
+ * collision without grepping their code.
+ *
+ * No side effects — the returned list is a fresh array even when
+ * `mounts` is empty, so callers never mutate the input reference.
+ */
+export function composeHandlersWithMounts(baseHandlers, mounts) {
+    if (!mounts || mounts.length === 0) {
+        return baseHandlers;
+    }
+    // Track ownership of every tool name so the error message can name
+    // the offending source. 'ggui' = one of ggui's native handlers;
+    // any other string = the mount's `name` that first claimed the tool.
+    const owner = new Map();
+    for (const h of baseHandlers)
+        owner.set(h.name, 'ggui');
+    const aggregated = [
+        ...baseHandlers,
+    ];
+    for (const mount of mounts) {
+        if (typeof mount.name !== 'string' || mount.name.length === 0) {
+            throw new Error('createGguiServer: every `mcpMounts` entry must carry a non-empty string `name` (for diagnostic telemetry + collision-error clarity).');
+        }
+        for (const mh of mount.handlers) {
+            // `outputSchema: {}` (empty `ZodRawShape`) silently strips
+            // `structuredContent` at the MCP SDK boundary — the handler
+            // can return `{ items: [...] }` and the wire answer is `{}`.
+            // Operators hitting this see success-looking responses with
+            // missing data and no diagnostic. Reject it at compose time
+            // so the failure arrives with the mount + tool names
+            // attached instead of showing up as a mystery at tools/call.
+            //
+            // Scope: mounted handlers only. ggui-native handlers are
+            // under repo ownership and already correctly shaped. If a
+            // legitimate no-output tool ever lands in a mount, declare
+            // `{ ok: z.literal(true) }` or equivalent — the zero-field
+            // case is never what you want over the wire.
+            if (typeof mh.outputSchema !== 'object' ||
+                mh.outputSchema === null ||
+                Object.keys(mh.outputSchema).length === 0) {
+                throw new Error(`createGguiServer: mount "${mount.name}" handler "${mh.name}" declares an empty \`outputSchema\` — this silently strips \`structuredContent\` at the MCP SDK boundary. Declare the fields the handler returns (e.g. \`outputSchema: { items: z.array(...) }\`). If the tool genuinely returns nothing, declare a sentinel like \`{ ok: z.literal(true) }\`.`);
+            }
+            const prior = owner.get(mh.name);
+            if (prior !== undefined) {
+                const priorLabel = prior === 'ggui'
+                    ? 'a ggui-native tool'
+                    : `mount "${prior}"`;
+                throw new Error(`createGguiServer: mount "${mount.name}" registers tool "${mh.name}" which collides with ${priorLabel}. Rename the tool or drop the duplicate mount.`);
+            }
+            owner.set(mh.name, mount.name);
+            aggregated.push(mh);
+        }
+    }
+    return aggregated;
+}
+/**
+ * Build a {@link WiredActionRouter} that dispatches wired-action
+ * hits to the matching mount handler's `handler(input, ctx)`. Zero-config composition for
+ * OSS `ggui serve` — when the operator declares `ggui.json#mcpMounts`,
+ * every mounted tool automatically becomes wire-dispatchable from
+ * a generated UI's `useAction` without additional glue.
+ *
+ * Ownership + scoping:
+ *   - Only MOUNT handlers participate. ggui-native handlers
+ *     (`ggui_push`, `ggui_handshake`, etc.) are platform tools and
+ *     deliberately NOT exposed as wire-dispatchable actions — a
+ *     component that tried to dispatch `ggui_push` would bypass the
+ *     agentic-loop contract.
+ *   - Name collisions across mounts are prevented at aggregation
+ *     time by {@link composeHandlersWithMounts}, so the first-match
+ *     lookup here is safe.
+ *
+ * Context synthesis:
+ *   - Each invocation gets a fresh {@link HandlerContext} with the
+ *     caller-supplied `appId` (typically the session's appId) + a
+ *     fresh request id. Mount handlers that read from storage scope
+ *     to this appId, matching the `/mcp` ingress behavior.
+ *   - The session-channel dispatcher additionally hands a
+ *     {@link WiredActionContext}. The runtime ctx the mount handler
+ *     sees is a structural superset
+ *     ({@link WiredMountContext}) so a JS-authored mount can call
+ *     `ctx.sendPropsUpdate(ctx.stackItemId, {...})` directly. The static
+ *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
+ *     untouched — tooling that doesn't read the wired fields keeps its
+ *     existing types.
+ *
+ * Returns `null` when `mounts` is empty/absent, signaling the
+ * composer to OMIT the `wiredActionRouter` opt entirely so servers
+ * with no mounts behave as if the router did not exist.
+ */
+export function composeWiredActionRouterFromMounts(mounts, resolveContext) {
+    if (!mounts || mounts.length === 0)
+        return null;
+    const byName = new Map();
+    for (const mount of mounts) {
+        for (const h of mount.handlers) {
+            // First-write-wins matches `composeHandlersWithMounts`'s
+            // collision-rejection order; the compose path throws before
+            // reaching this builder, so a duplicate here is dead code.
+            if (!byName.has(h.name))
+                byName.set(h.name, h);
+        }
+    }
+    return {
+        has(toolName) {
+            return byName.has(toolName);
+        },
+        async invoke(toolName, input, wiredCtx) {
+            const handler = byName.get(toolName);
+            if (!handler) {
+                // Unreachable in normal use — the session channel has()-gates
+                // before calling invoke. Thrown errors surface as TOOL_THREW
+                // envelopes, so the caller still gets a canonical shape.
+                throw new Error(`wiredActionRouter(mounts): no handler registered for '${toolName}'`);
+            }
+            // Synthesize the runtime ctx — structural superset of
+            // HandlerContext + WiredActionContext. The static
+            // `SharedHandler.handler` accepts `HandlerContext`; mounts that
+            // need the wired fields read them off the same `ctx` argument
+            // (TS via `WiredMountContext`, JS structurally).
+            const baseCtx = resolveContext();
+            const ctx = {
+                ...baseCtx,
+                sessionId: wiredCtx.sessionId,
+                stackItemId: wiredCtx.stackItemId,
+                sendPropsUpdate: wiredCtx.sendPropsUpdate,
+            };
+            return handler.handler(input, ctx);
+        },
+    };
+}

package/dist/oauth-login-types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * OAuth login provider seam.
+ *
+ * Locks the contract every OAuth-login consumer composes against:
+ *
+ *   - Provider implementations (`oauth-providers/{google,github}.ts`)
+ *     return one of these per configured provider.
+ *   - Storage (`oauth-providers-store.ts`) serializes config records
+ *     and hydrates concrete providers via the registered factory.
+ *   - Routes (`oauth-login.ts`) iterate the bound providers and call
+ *     `authorizeUrl` / `exchangeCode` per request.
+ *   - Console UI (`AdminOAuthProviders.tsx`) lists `providerId` /
+ *     `displayName` per record so the operator can paste secrets
+ *     into the right slot.
+ *
+ * Identity model: a successful OAuth callback mints a bearer for an
+ * `Identity` of `{ kind: 'user', userId: '${providerId}:${providerSubject}', roles: [] }`.
+ * Email is informational only — providers MAY return it (display in
+ * the operator's audit log + the user's `/settings` page), but the
+ * identity is always provider-namespaced. No email-based account
+ * linking — different providers ⇒ different identities, period.
+ *
+ * **Why no email-based linking?** A user's OAuth-provider email can
+ * change (they switch jobs, providers verify slowly). Linking by
+ * email would let an attacker who briefly controls an email at
+ * provider X impersonate the same user's account at provider Y.
+ * Provider-subject is the strongest cross-provider primary key the
+ * OAuth spec gives us. Future "link account" flows are explicit.
+ */
+import type { AuthResult } from '@ggui-ai/mcp-server-core';
+/**
+ * The runtime contract every concrete OAuth provider implements.
+ *
+ * Stateless by design — `authorizeUrl` builds the redirect URL from
+ * the caller-supplied state + PKCE challenge; `exchangeCode` swaps
+ * the callback `code` for the user's `providerSubject` (and optional
+ * email). All provider-specific config (client_id, client_secret,
+ * scopes, endpoint URLs) is captured at construction time inside the
+ * concrete impl — the routes don't need to know.
+ *
+ * **Implementation expectations:**
+ *
+ *   - `providerId` is operator-stable (`'google'`, `'github'`, ...).
+ *     The route `GET /ggui/oauth-login/:providerId/start` matches
+ *     this value, so changing it breaks bookmarks.
+ *   - `authorizeUrl` MUST URL-encode every query parameter — the
+ *     state token is HMAC-bound and may contain `+` / `=` characters.
+ *   - `exchangeCode` MUST send the `code_verifier` and the same
+ *     `redirect_uri` the authorize step used. PKCE `S256` is the
+ *     only method we support; providers that only support `plain`
+ *     are out of scope (Google, GitHub both support S256).
+ *   - `exchangeCode` MUST throw on any non-2xx provider response.
+ *     The route catches and 400s the callback (state mismatch and
+ *     network error are both "abort the flow"; finer-grained UX is
+ *     a follow-up).
+ *   - `providerSubject` MUST be the provider's stable user ID
+ *     (Google `sub`, GitHub `id`), NEVER the email. Anyone changing
+ *     this to email opens session fixation across email rotation.
+ */
+export interface OAuthLoginProvider {
+    /** Stable URL slug for this provider — `'google'`, `'github'`, ... */
+    readonly providerId: string;
+    /**
+     * Human-readable label for the operator's `/admin/oauth-providers`
+     * page and the end-user's `/login` button. May change per release;
+     * `providerId` is the stable wire field.
+     */
+    readonly displayName: string;
+    /**
+     * Build the provider's authorize URL. Caller supplies the HMAC-bound
+     * `state` token and the PKCE `codeChallenge` (S256-base64url-encoded
+     * SHA-256 of the verifier). The provider implementation appends its
+     * own `client_id`, `redirect_uri`, `scope`, and `code_challenge_method=S256`.
+     */
+    authorizeUrl(input: AuthorizeUrlInput): string;
+    /**
+     * Exchange the callback `code` for the user's identity. `codeVerifier`
+     * is the original PKCE plaintext the route stamped during /start.
+     * `redirectUri` is repeated here because some providers strict-match
+     * it against the authorize call (Google does; GitHub doesn't).
+     */
+    exchangeCode(input: ExchangeCodeInput): Promise<OAuthExchangeResult>;
+}
+export interface AuthorizeUrlInput {
+    readonly state: string;
+    readonly codeChallenge: string;
+    readonly redirectUri: string;
+}
+export interface ExchangeCodeInput {
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+}
+export interface OAuthExchangeResult {
+    /**
+     * Provider-stable user identifier. NEVER the email; that's a UX
+     * field. Used to mint `userId = '${providerId}:${providerSubject}'`.
+     */
+    readonly providerSubject: string;
+    /**
+     * Optional display email. If present, lands in audit metadata +
+     * `/settings` UI. Absent providers (or users who hide their email)
+     * are still authenticated; subject alone is sufficient identity.
+     */
+    readonly email?: string;
+    /**
+     * Optional display name. Same rules as `email` — UX only, never
+     * load-bearing for identity decisions.
+     */
+    readonly displayName?: string;
+}
+/**
+ * Storage-layer record. The serialized form sitting in
+ * `~/.ggui/oauth-providers.json`. Contains the per-provider client
+ * credentials the operator pasted at `/admin/oauth-providers` (or
+ * the env-override values if `GGUI_OAUTH_<PROVIDERID>_CLIENT_ID` /
+ * `GGUI_OAUTH_<PROVIDERID>_CLIENT_SECRET` are set).
+ *
+ * Storage is responsible for: file mode 0600, atomic writes, env
+ * override (env wins), and surfacing `enabled: false` records so the
+ * `/admin/oauth-providers` UI can render the slot without it being
+ * consumable by the routes.
+ */
+export interface OAuthProviderConfigRecord {
+    readonly providerId: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    /**
+     * Where the values came from. UI surfaces env-overridden providers
+     * as read-only ("configured (env)"); file-backed records are
+     * editable.
+     */
+    readonly source: 'file' | 'env';
+    /**
+     * Operator can disable a record without deleting it. `false` keeps
+     * the slot visible in the admin UI but excludes it from `/login`
+     * button rendering and route lookups.
+     */
+    readonly enabled: boolean;
+}
+/**
+ * The minimal AuthAdapter call shape OAuth callbacks use to mint a
+ * bearer. `source: 'oauth'` is the canonical provenance string —
+ * audit hooks branch on this to distinguish OAuth identity from
+ * pairing-issued bearers.
+ */
+export type OAuthAuthResult = AuthResult & {
+    source: 'oauth';
+};
+/**
+ * Compose the canonical user-id namespace for an OAuth identity.
+ * `userId = '${providerId}:${providerSubject}'`. Pure helper —
+ * exported here so every consumer (routes, storage, audit hooks)
+ * computes the same thing.
+ */
+export declare function composeOAuthUserId(input: {
+    readonly providerId: string;
+    readonly providerSubject: string;
+}): string;
+//# sourceMappingURL=oauth-login-types.d.ts.map

package/dist/oauth-login-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-login-types.d.ts","sourceRoot":"","sources":["../src/oauth-login-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAC/C;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GAAG,MAAM,CAET"}

package/dist/oauth-login-types.js

@@ -0,0 +1,9 @@
+/**
+ * Compose the canonical user-id namespace for an OAuth identity.
+ * `userId = '${providerId}:${providerSubject}'`. Pure helper —
+ * exported here so every consumer (routes, storage, audit hooks)
+ * computes the same thing.
+ */
+export function composeOAuthUserId(input) {
+    return `${input.providerId}:${input.providerSubject}`;
+}