@ggui-ai/mcp-server 0.9.0 → 0.11.0

package/dist/mcp-apps-outbound.js

@@ -31,7 +31,7 @@
  *   build target — per the design lock, the shell is served by the
  *   same `@ggui-ai/mcp-server` instance that mints the bootstrap.
  */
-import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, filterDescriptorsToContract, findBlueprintExact, spreadRenderMetaViewOntoSlice, wsOriginToHttpOrigin, } from "@ggui-ai/mcp-server-handlers/renders";
+import { deriveBundleOrigins, deriveContractBundle, derivePublicEnvProjection, deriveRenderMeta, filterDescriptorsToContract, findBlueprintExact, resolveSliceTheme, spreadRenderMetaViewOntoSlice, wsOriginToHttpOrigin, } from "@ggui-ai/mcp-server-handlers/renders";
 import { RESOURCE_NOT_FOUND_MESSAGE, deriveContextDefault, isRecord, resolveAppGadgets, resourceReadErrorToJsonRpc, } from "@ggui-ai/protocol";
 import { GGUI_RENDER_RESOURCE_MIME, GGUI_RENDER_RESOURCE_URI, GGUI_RENDER_SHELL_SURFACE, MCP_APPS_UI_CAPABILITY, MCP_APP_BOOTSTRAP_FAILED_TYPE, asGguiRenderBootstrap, composeSessionApiUrls, deriveContextName, escapeInlineScript, gguiShellHtml, parseEpochUri, toMcpAppEnvelope, } from "@ggui-ai/protocol/integrations/mcp-apps";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -287,13 +287,66 @@ window.addEventListener('message',function(ev){
     // at the top level.
     var specMeta=readMetaFromCallToolResult(m.params);
     if(specMeta){mountFromMeta(specMeta);return;}
-    // R5 (2026-05-26) -- the /r/<shortCode> HTTP fallback was removed
-    // along with the bearer-by-obscurity model. Hosts that strip
-    // _meta on the tool-result wire have no fallback path here;
-    // spec-canonical hosts deliver meta inline and land in the branch
-    // above.
+    // Read-plane door (ggui#537). A server running the read-plane-only
+    // posture publishes only the view's IDENTITY on the result -- the
+    // ui:// locator on structuredContent.resourceUri and the spec
+    // pointer _meta.ui.resourceUri -- and no bootstrap material. The
+    // per-render resource that locator names is the self-contained
+    // shell, whose document inlines the very envelope this shell needs;
+    // ask the HOST to read it (resources/read, proxied by the host's
+    // own MCP client -- no fetch from this sandbox, so a host CSP with
+    // no connect-src to the server is not in the way). R5 (2026-05-26)
+    // removed the /r/<shortCode> HTTP fallback with the bearer-by-
+    // obscurity model; this door is the spec-canonical replacement.
+    var locator=readLocatorFromCallToolResult(m.params);
+    if(locator){mountFromLocator(locator);return;}
   }
 });
+function readLocatorFromCallToolResult(params){
+  if(!params||typeof params!=='object')return null;
+  var sc=params.structuredContent, meta=params._meta, uri=null;
+  if(sc&&typeof sc==='object'&&typeof sc.resourceUri==='string')uri=sc.resourceUri;
+  else if(meta&&typeof meta==='object'&&meta.ui&&typeof meta.ui==='object'&&typeof meta.ui.resourceUri==='string')uri=meta.ui.resourceUri;
+  if(!uri||uri.indexOf('ui://ggui/render/')!==0)return null;
+  return uri;
+}
+function envelopeFromResourceDoc(text){
+  // The per-render self-contained shell inlines its envelope on ONE
+  // line inside its meta script tag: globalThis.__GGUI_META__ = {...};
+  // (protocol gguiShellHtml). The JSON is angle-bracket-escaped by the
+  // assembler, so the first ';' followed by the closing script tag
+  // after the marker is the terminator.
+  if(typeof text!=='string')return null;
+  var marker='globalThis.__GGUI_META__ = ';
+  var start=text.indexOf(marker);
+  if(start<0)return null;
+  start+=marker.length;
+  var end=text.indexOf(';<'+'/script>',start);
+  if(end<0)return null;
+  try{var env=JSON.parse(text.slice(start,end));}catch(e){return null;}
+  return (env&&typeof env==='object'&&env['ai.ggui/render']&&typeof env['ai.ggui/render'].runtimeUrl==='string')?env:null;
+}
+async function mountFromLocator(uri){
+  if(mounted)return;
+  setOverlay('Resolving view…');
+  var res;
+  try{res=await postRpc('resources/read',{uri:uri});}
+  catch(e){
+    var rmsg='READ_DOOR_FAILED: the host could not read '+uri+' -- '+(e&&e.message||JSON.stringify(e));
+    showFailure('This view could not be resolved',rmsg,function(){mountFromLocator(uri);});
+    postBootstrapFailed('MALFORMED_BOOTSTRAP',rmsg);
+    return;
+  }
+  var c=res&&res.contents&&res.contents[0];
+  var env=envelopeFromResourceDoc(c&&c.text);
+  if(!env){
+    var emsg='MALFORMED_BOOTSTRAP: resource '+uri+' carried no ai.ggui/render envelope with a runtimeUrl.';
+    showFailure('This view could not start',emsg,function(){mountFromLocator(uri);});
+    postBootstrapFailed('MALFORMED_BOOTSTRAP',emsg);
+    return;
+  }
+  mountFromMeta(env);
+}
 // Named so the failure card's Retry can re-run the whole handshake —
 // a host that missed or rejected the first ui/initialize may answer a
 // second (observed with hosts that attach their listener late).
@@ -351,10 +404,15 @@ startInit();
 // diverged. Painting the served document's own surface here removes the
 // dependency on a browser honoring iframe transparency.
 //
-// Value-resolution only — no `--ggui-*` token added or renamed. The
-// constant itself lives with the protocol host-helper (the shared
-// self-contained-shell assembler paints the same surface); imported
-// above and reused here for the thin postMessage shell.
+// The paint is inline, so no stylesheet `background` rule can undo
+// it — which is why the constant's `var()` chain opens with the
+// `--ggui-shell-background` override point: content that KNOWS its
+// host composites behind the document (the runtime's system-card
+// layer inside Claude) sets that property from its stylesheet and
+// the inline value re-resolves to transparent in place. See
+// `GGUI_RENDER_SHELL_SURFACE` in the protocol host-helper (the
+// shared self-contained-shell assembler paints the same surface);
+// imported above and reused here for the thin postMessage shell.
 // `#ggui-root` here is LOAD-BEARING for the shell script (NOT a React
 // mount target): the inline script grabs it as `rootEl` for the
 // pre-mount overlays ("Initializing…", "Waiting for tool result…",
@@ -530,13 +588,15 @@ function buildCspMeta(publicBaseUrl,
  */
 runtimeUrl, 
 /**
- * Origins of server-stamped fetch/stream URLs (`sseUrl`,
+ * Origins of server-stamped connect URLs (`wsUrl`, `sseUrl`,
  * `pollingUrl`) — each parseable entry's origin is unioned into
- * `connectDomains` (deduplicated). Same-origin deployments add
- * nothing new; split-origin session APIs (dedicated streaming host)
- * would otherwise be silently blocked by `connect-src` on
- * spec-compliant hosts — EventSource and fetch are both
- * connect-src-governed.
+ * `connectDomains` (deduplicated), scheme preserved (`ws`/`wss` are
+ * WHATWG special schemes, so a `wss://` entry contributes its
+ * `wss://` origin). Same-origin deployments add nothing new;
+ * split-origin live channels or session APIs would otherwise be
+ * silently blocked by `connect-src` on spec-compliant hosts —
+ * WebSocket, EventSource, and fetch are all connect-src-governed,
+ * and the base's ws-twin flip only covers the base's own host.
  */
 extraConnectUrls) {
     const source = publicBaseUrl ?? runtimeUrl;
@@ -805,6 +865,11 @@ export function buildSelfContainedShell(opts) {
                 ...(opts.codeHash !== undefined ? { codeHash: opts.codeHash } : {}),
             }
             : {}),
+        // Strict-CSP module-variant twin — only WITH a raw static carrier
+        // (the protocol parser drops it otherwise).
+        ...(!isSystem && (hasCodeUrl || hasCodeB64) && opts.codeModuleUrl !== undefined
+            ? { codeModuleUrl: opts.codeModuleUrl }
+            : {}),
         ...(!isSystem && hasCodeB64 ? { codeB64: opts.codeB64 } : {}),
         ...(opts.propsJson !== undefined ? { propsJson: opts.propsJson } : {}),
         ...(opts.contextSlots !== undefined && opts.contextSlots.length > 0
@@ -836,7 +901,12 @@ export function buildSelfContainedShell(opts) {
     // standalone served iframe (claude.ai per-render resource shells,
     // `/r/<shortCode>`), never inlined into a host page — so it paints
     // its own theme-surface backdrop. See `GguiShellHtmlOptions` for the
-    // Safari white-canvas rationale.
+    // Safari white-canvas rationale. System-kind renders keep this
+    // posture too: the surface paint resolves through the
+    // `--ggui-shell-background` override point, so the card layer —
+    // the only layer that can detect a compositing host at runtime —
+    // drops the backdrop to transparent itself where that is right,
+    // and every other context keeps the per-browser-consistent paint.
     return gguiShellHtml(bootstrap, { background: "surface" });
 }
 /**
@@ -1539,6 +1609,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // the mount.
         let codeUrl;
         let codeHash;
+        let codeModuleUrl;
         let contractHash;
         let validatorsUrl;
         if (!isSystem && opts.codeStore && opts.codeBaseUrl) {
@@ -1548,6 +1619,13 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 codeHash = hash;
                 const base = opts.codeBaseUrl.replace(/\/$/, "");
                 codeUrl = `${base}/code/${hash}.js`;
+                // Strict-CSP module-variant twin (ggui#522 slice 2) — a
+                // decline (`undefined`) just means the blob ladder carries it.
+                codeModuleUrl = opts.mintCodeModuleUrl?.({
+                    code: picked.componentCode,
+                    hash,
+                    base,
+                });
             }
             catch (cause) {
                 channelFault ??= { cause };
@@ -1677,6 +1755,7 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                         ? {
                             codeUrl,
                             ...(codeHash !== undefined ? { codeHash } : {}),
+                            ...(codeModuleUrl !== undefined ? { codeModuleUrl } : {}),
                         }
                         : {}),
                     // Inline fetch-free channel (size-capped, projected by
@@ -1694,8 +1773,21 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                     ...(wsExpiresAt !== undefined ? { expiresAt: wsExpiresAt } : {}),
                 }
                 : {}),
-            ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
-            ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+            // Layered theme — the SAME resolver the tool-result slice uses
+            // (live pick > per-render override on this render > static
+            // ggui.json), so a `ggui_render({ themeId })` override survives a
+            // mount-by-read (ggui#539). The picked source IS the committed
+            // render, so its `themeId` is the override the emitter read at
+            // commit time — component variant only, exactly the emitter's
+            // own narrowing (render.ts resultMeta): mcpApps / system renders
+            // carry no user-facing theme. Keys stay absent when unresolved.
+            ...resolveSliceTheme(opts, picked.source.type !== "mcpApps" && picked.source.type !== "system"
+                ? picked.source.themeId
+                : undefined, 
+            // ggui#589 — the session theme's own mode, from the SAME
+            // projection (`view`, derived above) that emits the `theme`
+            // object on this shell's envelope.
+            view.theme?.mode),
             // State + policy view fields (theme overlay, propsJson,
             // contextSlots, permissionsPolicy, gadgets, #483 epoch) — ONE
             // shared spread so the resource-served shell cannot drift from
@@ -1726,16 +1818,23 @@ export function registerGguiRenderResourceTemplate(server, opts) {
         // derives these via deriveBundleOrigins; this is the per-call
         // resource mirror.
         const gadgetOrigins = deriveBundleOrigins(picked.source);
-        // Per-render CSP base: recompute with the stamped session-API
-        // URLs so their origins ride `connectDomains` (EventSource +
-        // fetch are connect-src-governed). Same-origin stamps dedupe to
-        // the registration-time declaration; a base derived from the
-        // wsUrl origin flip (publicBaseUrl absent) adds the flip origin
-        // that would otherwise be silently blocked.
-        const renderCspBase = sessionApiUrls !== undefined
+        // Per-render CSP base: recompute with the stamped live-channel +
+        // session-API URLs so their origins ride `connectDomains`
+        // (WebSocket, EventSource, and fetch are all connect-src-governed).
+        // The stamped `wsUrl` MUST be its own entry: CSP never
+        // cross-translates `https://` ↔ `wss://`, and the base's ws-twin
+        // flip only covers deployments whose base origin IS the ws host —
+        // when `publicBaseUrl` is absent and the runtime bundle lives on
+        // an assets CDN origin, the flip declares the CDN's wss twin while
+        // the actual socket host goes undeclared and the live channel dies
+        // in the mounted iframe (#479, observed as the cloud-render
+        // capstone's CSP block). Same-origin stamps dedupe to the
+        // registration-time declaration.
+        const renderCspBase = sessionApiUrls !== undefined || wsUrl !== undefined
             ? buildCspMeta(opts.publicBaseUrl, opts.runtimeUrl, [
-                sessionApiUrls.sseUrl,
-                sessionApiUrls.pollingUrl,
+                wsUrl,
+                sessionApiUrls?.sseUrl,
+                sessionApiUrls?.pollingUrl,
             ])
             : templateCspMeta;
         return shellContents(uri, html, augmentCspMeta(gadgetOrigins, renderCspBase));
@@ -1964,8 +2063,11 @@ export function registerGguiRenderResourceTemplate(server, opts) {
                 appId: opts.defaultAppIdFallback,
                 blueprint,
                 runtimeUrl: opts.runtimeUrl,
-                ...(opts.themeId !== undefined ? { themeId: opts.themeId } : {}),
-                ...(opts.themeMode !== undefined ? { themeMode: opts.themeMode } : {}),
+                // No render row exists on this branch, so there is no
+                // per-render override to honor (and no session theme — the
+                // ggui#589 layer is honestly absent) — but the live pick still
+                // beats the static preset, same resolver as every other shell.
+                ...resolveSliceTheme(opts, undefined, undefined),
                 ...(opts.codeStore !== undefined ? { codeStore: opts.codeStore } : {}),
                 ...(opts.codeBaseUrl !== undefined ? { codeBaseUrl: opts.codeBaseUrl } : {}),
             });

package/dist/mcp-endpoint-routes.d.ts

@@ -80,6 +80,12 @@ interface MountOptions {
      * transport.
      */
     readonly controlHandlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /**
+     * The control plane's ops-tool name set (captured by
+     * `buildControlService` before audience-stripping). Drives the
+     * transport-level anonymous-ops OAuth challenge (ggui#505).
+     */
+    readonly controlOpsToolNames: ReadonlySet<string>;
     /** Validated isolated-service list (`validateMcpServices` output). */
     readonly mcpServices: ReadonlyArray<McpService>;
     /** Request-scoped HandlerContext storage shared with the handlers. */

package/dist/mcp-endpoint-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA2U1D"}
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAM7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IACjF;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA+Z1D"}

package/dist/mcp-endpoint-routes.js

@@ -31,6 +31,7 @@
  * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
  * rules.
  */
+import { isRecord } from "@ggui-ai/protocol";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { randomUUID } from "node:crypto";
 import { resolveIdentity, UnauthenticatedError } from "./auth.js";
@@ -64,7 +65,28 @@ function resolveWwwAuthResourcePath(req, perAppRouting) {
  * routes self-register.
  */
 export function mountMcpEndpoints(opts) {
-    const { app, logger, auth, info, handlers, controlHandlers, mcpServices, als, appIdFromIdentity, universalMcpPath, perAppRouting, oauthEnabled, oauthIssuerUrl, errorMapper, buildMcpOptions, } = opts;
+    const { app, logger, auth, info, handlers, controlHandlers, controlOpsToolNames, mcpServices, als, appIdFromIdentity, universalMcpPath, perAppRouting, oauthEnabled, oauthIssuerUrl, errorMapper, buildMcpOptions, } = opts;
+    /**
+     * OAuth auto-negotiation for the control plane (ggui#505): the first
+     * tool name in the request body that is an ops tool, or `null` when
+     * the request contains none. JSON-RPC bodies may be a single message
+     * or a batch; a batch containing ANY ops call challenges as a whole
+     * (mixed anonymous batches are not a supported shape).
+     *
+     * External-boundary narrowing via `isRecord` — the body is unvalidated
+     * wire input here; the MCP transport re-validates after dispatch.
+     */
+    const findOpsToolCall = (body, opsToolNames) => {
+        const messages = Array.isArray(body) ? body : [body];
+        for (const m of messages) {
+            if (!isRecord(m) || m.method !== "tools/call" || !isRecord(m.params))
+                continue;
+            const name = m.params.name;
+            if (typeof name === "string" && opsToolNames.has(name))
+                return name;
+        }
+        return null;
+    };
     const makeMcpHandler = (routeHandlers, handlerOpts) => async (req, res) => {
         const requestId = typeof req.headers["x-request-id"] === "string"
             ? req.headers["x-request-id"]
@@ -154,6 +176,37 @@ export function mountMcpEndpoints(opts) {
             });
             return;
         }
+        // OAuth auto-negotiation (ggui#505) — anonymous ops calls get a
+        // transport 401 BEFORE dispatch, with the standards trigger in
+        // the header AND the actionable guidance agents read in the
+        // body. Runs only when the route opted in (the control plane)
+        // and only for resolved-anonymous callers naming an ops tool —
+        // every other message on the route keeps the anonymous-capable
+        // design-time posture. This makes the documented
+        // AuthRequiredError→401 mapping observable at the transport; the
+        // per-tool auth gate stays as defense-in-depth for any path that
+        // reaches dispatch.
+        if (handlerOpts?.anonymousOpsChallenge !== undefined && identity.source === "anonymous") {
+            const opsToolName = findOpsToolCall(req.body, handlerOpts.anonymousOpsChallenge);
+            if (opsToolName !== null) {
+                reqLogger.info("anonymous_ops_call_challenged", { tool: opsToolName });
+                if (oauthEnabled) {
+                    res.setHeader("WWW-Authenticate", buildWwwAuthenticate(resolveIssuerUrl(req, oauthIssuerUrl), CONTROL_PATH));
+                }
+                res.status(401).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: `${opsToolName} is an operator tool and needs an authenticated caller. ` +
+                            `Present a bearer token this deployment accepts, or complete the OAuth flow ` +
+                            `advertised in WWW-Authenticate (universal connector keys come from the ` +
+                            `console: Connector keys → New key, leave the app unset).`,
+                    },
+                    id: null,
+                });
+                return;
+            }
+        }
         // Per-tenant URL routing. When `perAppRouting`
         // is configured AND the request matched the per-app path
         // `/:${paramName}/mcp`, Express populates `req.params[paramName]`
@@ -202,6 +255,15 @@ export function mountMcpEndpoints(opts) {
             // context shape; OSS handlers continue to ignore both fields.
             ...(identity.identity.kind === "app" ? { apiKeyHash: identity.identity.apiKeyHash } : {}),
             ...(identity.identity.kind === "user" ? { userId: identity.identity.userId } : {}),
+            // What the credential itself may act on, when the adapter
+            // distinguishes credential scopes. Identity-independent by
+            // design: one account can present a key bound to a single app
+            // on one request and an account-wide key on the next, and the
+            // resolved userId is the same string both times — so the scope
+            // has to ride the request, not be re-derived from the identity.
+            ...(identity.credentialScope !== undefined
+                ? { credentialScope: identity.credentialScope }
+                : {}),
         };
         reqLogger.debug?.("mcp_request", { appId: ctx.appId });
         const mcp = buildMcpServer(info, routeHandlers, () => als.getStore() ?? ctx, reqLogger, {
@@ -273,6 +335,10 @@ export function mountMcpEndpoints(opts) {
     const controlMcpHandler = makeMcpHandler(controlHandlers, {
         anonymous: true,
         rejectFederated: true,
+        // The control service captures this set BEFORE stripAudience
+        // erases the tags — filtering `controlHandlers` here would yield
+        // an empty set and silently disable the challenge (ggui#505).
+        anonymousOpsChallenge: controlOpsToolNames,
     });
     // Universal endpoint — `appId` resolved from the auth identity via
     // `appIdFromIdentity`. Cloud `mcp.ggui.ai` deployments resolve this

package/dist/oauth-as-routes.d.ts

@@ -37,6 +37,17 @@ interface MountOptions {
         readonly paramName: string;
         readonly pathPrefix?: string;
     };
+    /**
+     * Control-plane mount path (`/control`). When set, the control
+     * plane becomes an RFC 9728/8707-nameable resource: both PRM
+     * discovery forms mount for it, and hosts can complete the OAuth
+     * ceremony naming it directly instead of consenting against the
+     * data plane and reusing the bearer (ggui#505). The minted key is
+     * universal — the consent page extracts an appId only from the
+     * per-app resource shape, and control-plane ops are account-level
+     * by design.
+     */
+    readonly controlPath?: string;
     /** Auth adapter the consent-submit handler resolves bearers against. */
     readonly auth: AuthAdapter;
     /**

package/dist/oauth-as-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-as-routes.d.ts","sourceRoot":"","sources":["../src/oauth-as-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAyH5E"}
+{"version":3,"file":"oauth-as-routes.d.ts","sourceRoot":"","sources":["../src/oauth-as-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAOL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAsI5E"}

package/dist/oauth-as-routes.js

@@ -25,11 +25,19 @@ import { handleAuthorizationServerMetadata, handleAuthorizeGet, handleAuthorizeP
  * insecure flows). Returns nothing — the routes self-register.
  */
 export function mountOAuthAuthorizationServerRoutes(opts) {
-    const { app, oauthConfig, oauthStorage, universalMcpPath, perAppRouting, auth, getPairingService, } = opts;
+    const { app, oauthConfig, oauthStorage, universalMcpPath, perAppRouting, controlPath, auth, getPairingService, } = opts;
     // `trust proxy` so req.protocol + req.host honor X-Forwarded-Proto +
     // X-Forwarded-Host.
     app.set("trust proxy", true);
     app.get("/.well-known/oauth-protected-resource", (req, res) => handleProtectedResourceMetadata(req, res, oauthConfig, universalMcpPath));
+    // Control-plane PRM (ggui#505) — both discovery forms, mirroring the
+    // universal endpoint's pair below: the suffix form for grandfathered
+    // clients and the RFC 9728 §3.1 path-inserted form claude.ai's
+    // connect flow actually fetches. Same document either way.
+    if (controlPath !== undefined) {
+        app.get(`${controlPath}/.well-known/oauth-protected-resource`, (req, res) => handleProtectedResourceMetadata(req, res, oauthConfig, controlPath));
+        app.get(`/.well-known/oauth-protected-resource${controlPath}`, (req, res) => handleProtectedResourceMetadata(req, res, oauthConfig, controlPath));
+    }
     // Per-app protected-resource metadata (RFC 9728 per-resource
     // discovery). When `perAppRouting` is configured,
     // mount a second well-known endpoint under the same path prefix

package/dist/runtime-bundle-hash.d.ts

@@ -40,4 +40,16 @@ export declare function insertRuntimeBundleHash(urlOrPath: string, hash: string,
  * revalidated.
  */
 export declare function resolveHashedRuntimeBundleUrl(plainUrl: string, bundleFile?: string): string;
+/**
+ * The 12-hex runtime-bundle content hash for the bundle at
+ * `bundleFile` (default: the workspace's built bundle — the same file
+ * `createGguiServer` hashes, so both derive the same value), or
+ * `undefined` when the bundle is unreadable. Deployments that compose
+ * their own render handler (the cloud pod's `handlers: tools` shape)
+ * use this to build a `createCodeModuleUrlMinter` that stamps the SAME
+ * `<rt>` the co-resident factory's variant route serves (ggui#522
+ * slice 2) — re-deriving the scheme by hand is how the codeUrl binding
+ * drifted in slice 1.
+ */
+export declare function resolveRuntimeBundleHash(bundleFile?: string): string | undefined;
 //# sourceMappingURL=runtime-bundle-hash.d.ts.map

package/dist/runtime-bundle-hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-bundle-hash.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,sEAAsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAA4B,GACvC,MAAM,CAYR"}
+{"version":3,"file":"runtime-bundle-hash.d.ts","sourceRoot":"","sources":["../src/runtime-bundle-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,sEAAsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAA4B,GACvC,MAAM,CAYR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,GAAE,MAA4B,GACvC,MAAM,GAAG,SAAS,CAMpB"}

package/dist/runtime-bundle-hash.js

@@ -64,3 +64,22 @@ export function resolveHashedRuntimeBundleUrl(plainUrl, bundleFile = RUNTIME_BUN
     const plainName = RUNTIME_BUNDLE_URL_PATH.slice(RUNTIME_BUNDLE_URL_PATH.lastIndexOf("/") + 1);
     return insertRuntimeBundleHash(plainUrl, computeRuntimeBundleHash(bytes), plainName);
 }
+/**
+ * The 12-hex runtime-bundle content hash for the bundle at
+ * `bundleFile` (default: the workspace's built bundle — the same file
+ * `createGguiServer` hashes, so both derive the same value), or
+ * `undefined` when the bundle is unreadable. Deployments that compose
+ * their own render handler (the cloud pod's `handlers: tools` shape)
+ * use this to build a `createCodeModuleUrlMinter` that stamps the SAME
+ * `<rt>` the co-resident factory's variant route serves (ggui#522
+ * slice 2) — re-deriving the scheme by hand is how the codeUrl binding
+ * drifted in slice 1.
+ */
+export function resolveRuntimeBundleHash(bundleFile = RUNTIME_BUNDLE_FILE) {
+    try {
+        return computeRuntimeBundleHash(fs.readFileSync(bundleFile));
+    }
+    catch {
+        return undefined;
+    }
+}