@ggui-ai/mcp-server 0.8.0 → 0.10.0

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

@@ -46,6 +46,22 @@ interface PerAppRouting {
     readonly pathPrefix?: string;
     readonly authorize?: (urlAppId: string, identity: AuthResult) => Promise<void>;
 }
+/**
+ * Return shape for an `errorMapper` hook — a domain error mapped onto
+ * an HTTP/JSON-RPC response triple, with optional response headers.
+ *
+ * `headers` is deliberately generic HTTP plumbing (e.g. `Retry-After`
+ * on a `503`), not a deployment-specific concept — any operator
+ * mapping a domain error to a status code that conventionally carries
+ * a header can use it.
+ */
+export interface ErrorMapperResult {
+    readonly status: number;
+    readonly code: number;
+    readonly message: string;
+    /** Response headers to set before the JSON body is written. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
 interface MountOptions {
     /** Express app to mount onto. */
     readonly app: Express;
@@ -64,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. */
@@ -79,11 +101,7 @@ interface MountOptions {
     /** Operator-configured issuer URL override (OAuth). */
     readonly oauthIssuerUrl?: string;
     /** Operator-supplied error → HTTP/JSON-RPC mapping hook. */
-    readonly errorMapper?: (err: unknown) => {
-        readonly status: number;
-        readonly code: number;
-        readonly message: string;
-    } | undefined;
+    readonly errorMapper?: (err: unknown) => ErrorMapperResult | undefined;
     /**
      * Per-boot `buildMcpServer` options. Assembled once by the composer
      * (every input is fixed at composition time); the handler spreads a

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,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,CACrB,GAAG,EAAE,OAAO,KACT;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC9F;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4U1D"}
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"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"}

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, {
@@ -235,6 +297,8 @@ export function mountMcpEndpoints(opts) {
                     }
                 }
                 if (mapped) {
+                    if (mapped.headers)
+                        res.set(mapped.headers);
                     res.status(mapped.status).json({
                         jsonrpc: "2.0",
                         error: { code: mapped.code, message: mapped.message },
@@ -271,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,CAwE5E"}
+{"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
@@ -66,6 +74,42 @@ export function mountOAuthAuthorizationServerRoutes(opts) {
             handleProtectedResourceMetadata(req, res, oauthConfig, `${pathPrefix}/${appId}`);
         });
     }
+    // ── RFC 9728 §3.1 path-INSERTED discovery ──────────────────────────
+    // The RFC forms the metadata URL by inserting the well-known
+    // component BETWEEN origin and resource path:
+    //   resource https://host/apps/<id>
+    //   → https://host/.well-known/oauth-protected-resource/apps/<id>
+    // The suffix-form routes above (`<path>/.well-known/...`) predate the
+    // final RFC and STAY for grandfathered clients. claude.ai's connector
+    // connect flow (observed 2026-08-12) fetches ONLY the inserted form —
+    // its absence 404'd the discovery chain, which surfaced as "Couldn't
+    // register with GGUI's sign-in service" on every NEW connect: a
+    // launch-day onboarding blocker. Both forms serve the identical
+    // document.
+    if (universalMcpPath !== "/") {
+        app.get(`/.well-known/oauth-protected-resource${universalMcpPath}`, (req, res) => handleProtectedResourceMetadata(req, res, oauthConfig, universalMcpPath));
+    }
+    if (perAppRouting !== undefined) {
+        const { paramName, pathPrefix = "" } = perAppRouting;
+        app.get(`/.well-known/oauth-protected-resource${pathPrefix}/:${paramName}`, (req, res) => {
+            const appId = req.params[paramName];
+            if (typeof appId !== "string" || appId.length === 0) {
+                res.status(404).json({ error: "not_found" });
+                return;
+            }
+            handleProtectedResourceMetadata(req, res, oauthConfig, `${pathPrefix}/${appId}`);
+        });
+        // Path-inserted AS-metadata twin (RFC 8414 §3.1). Our issuer is
+        // origin-only, so the ROOT document is the normative one — but
+        // several MCP clients derive an AS-metadata URL by inserting into
+        // the RESOURCE path when the protected-resource fetch fails or
+        // races. Serving the identical document here is spec-tolerant and
+        // keeps their fallback chain alive instead of dead-ending DCR.
+        app.get(`/.well-known/oauth-authorization-server${pathPrefix}/:${paramName}`, (req, res) => handleAuthorizationServerMetadata(req, res, oauthConfig));
+    }
+    if (universalMcpPath !== "/") {
+        app.get(`/.well-known/oauth-authorization-server${universalMcpPath}`, (req, res) => handleAuthorizationServerMetadata(req, res, oauthConfig));
+    }
     app.get("/.well-known/oauth-authorization-server", (req, res) => handleAuthorizationServerMetadata(req, res, oauthConfig));
     app.post("/oauth/register", (req, res) => {
         void handleRegister(req, res, oauthConfig, oauthStorage);

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO5E,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3E;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,wDAAwD;IACxD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC9D,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,WAAW,IAAI,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAChD;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAErD,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAQ7D,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAIzD,WAAW,IAAI,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAU/C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMpD;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,YAAY,GAAE,MAAW,GACxB,MAAM,CAIR;AAuCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,MAAe,GACvB,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,GAClB,IAAI,CAaN;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAwCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,WAAW,EACjB,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,GACrC,OAAO,CAAC,IAAI,CAAC,CAmHf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAiFf"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/oauth.js

@@ -143,7 +143,14 @@ export function resolveIssuerUrl(req, configured) {
  */
 export function buildWwwAuthenticate(issuerUrl, resourcePath = '') {
     const normalized = resourcePath.replace(/\/$/, '');
-    const resourceMetadataUrl = `${issuerUrl}${normalized}/.well-known/oauth-protected-resource`;
+    // RFC 9728 §3.1 path-INSERTED form — the well-known component goes
+    // BETWEEN origin and resource path (`/.well-known/oauth-protected-
+    // resource/apps/<id>`), NOT appended after it. The pre-RFC suffix
+    // form this header used to advertise is still SERVED (grandfathered
+    // clients), but the advert must be the spec shape: claude.ai's
+    // connect flow follows this header verbatim and 404'd on the suffix
+    // URL, dead-ending Dynamic Client Registration for new connects.
+    const resourceMetadataUrl = `${issuerUrl}/.well-known/oauth-protected-resource${normalized}`;
     return `Bearer realm="mcp", resource_metadata="${resourceMetadataUrl}"`;
 }
 // =============================================================================

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

@@ -0,0 +1,55 @@
+/**
+ * Content-hash naming for the iframe-runtime bundle URL (#472).
+ *
+ * ONE derivation, three consumers:
+ *
+ *   - `createGguiServer` (server.ts) hashes the captured bundle bytes,
+ *     mounts the immutable twin route, and rewrites the stamped
+ *     `runtimeUrl` — see the "Content-hashed runtime URL" block there.
+ *   - `mountRuntimeBundleRoute` serves the hashed name it is handed.
+ *   - Deployments that compose their own render handler (bypassing the
+ *     factory's default handler set) mint an absolute `runtimeUrl`
+ *     themselves; {@link resolveHashedRuntimeBundleUrl} lets them stamp
+ *     the SAME hashed name the co-resident factory mounts, instead of
+ *     re-deriving the scheme by hand and drifting.
+ *
+ * The scheme: `sha256(bytes)` truncated to 12 hex chars, inserted
+ * before the filename's extension — `iframe-runtime.js` →
+ * `iframe-runtime.<hash>.js`. 12 chars (48 bits) is plenty for
+ * cache-busting across deploys; this is not an integrity check (SRI
+ * would be a separate, full-length hash).
+ */
+/** Truncated content hash used in the bundle's immutable URL name. */
+export declare function computeRuntimeBundleHash(bytes: Buffer): string;
+/**
+ * Insert `hash` into `urlOrPath`'s filename, but ONLY when that
+ * filename is exactly `plainName` — a URL pointing at a foreign copy
+ * of the bundle (different name) is returned untouched, because the
+ * foreign host serves only the name the operator configured. Applies
+ * to both bare paths (`/_ggui/iframe-runtime.js`) and absolute URLs
+ * (`https://cdn.example.com/_ggui/iframe-runtime.js`).
+ */
+export declare function insertRuntimeBundleHash(urlOrPath: string, hash: string, plainName: string): string;
+/**
+ * Rewrite `plainUrl` (an absolute URL or path ending in the default
+ * bundle filename) to its content-hashed twin, hashing the bundle at
+ * `bundleFile` (default: the workspace's built bundle — the same file
+ * `createGguiServer` serves, so both stamp the same name). Falls back
+ * to `plainUrl` unchanged when the bundle is unreadable — the plain
+ * `no-cache` route always exists, so the fallback stays correct, just
+ * 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

@@ -0,0 +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;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,GAAE,MAA4B,GACvC,MAAM,GAAG,SAAS,CAMpB"}

package/dist/runtime-bundle-hash.js

@@ -0,0 +1,85 @@
+/**
+ * Content-hash naming for the iframe-runtime bundle URL (#472).
+ *
+ * ONE derivation, three consumers:
+ *
+ *   - `createGguiServer` (server.ts) hashes the captured bundle bytes,
+ *     mounts the immutable twin route, and rewrites the stamped
+ *     `runtimeUrl` — see the "Content-hashed runtime URL" block there.
+ *   - `mountRuntimeBundleRoute` serves the hashed name it is handed.
+ *   - Deployments that compose their own render handler (bypassing the
+ *     factory's default handler set) mint an absolute `runtimeUrl`
+ *     themselves; {@link resolveHashedRuntimeBundleUrl} lets them stamp
+ *     the SAME hashed name the co-resident factory mounts, instead of
+ *     re-deriving the scheme by hand and drifting.
+ *
+ * The scheme: `sha256(bytes)` truncated to 12 hex chars, inserted
+ * before the filename's extension — `iframe-runtime.js` →
+ * `iframe-runtime.<hash>.js`. 12 chars (48 bits) is plenty for
+ * cache-busting across deploys; this is not an integrity check (SRI
+ * would be a separate, full-length hash).
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { RUNTIME_BUNDLE_FILE, RUNTIME_BUNDLE_URL_PATH } from "@ggui-ai/iframe-runtime/server";
+/** Truncated content hash used in the bundle's immutable URL name. */
+export function computeRuntimeBundleHash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+}
+/**
+ * Insert `hash` into `urlOrPath`'s filename, but ONLY when that
+ * filename is exactly `plainName` — a URL pointing at a foreign copy
+ * of the bundle (different name) is returned untouched, because the
+ * foreign host serves only the name the operator configured. Applies
+ * to both bare paths (`/_ggui/iframe-runtime.js`) and absolute URLs
+ * (`https://cdn.example.com/_ggui/iframe-runtime.js`).
+ */
+export function insertRuntimeBundleHash(urlOrPath, hash, plainName) {
+    const dot = plainName.lastIndexOf(".");
+    const hashedName = dot === -1
+        ? `${plainName}.${hash}`
+        : `${plainName.slice(0, dot)}.${hash}${plainName.slice(dot)}`;
+    if (!urlOrPath.endsWith(`/${plainName}`) && urlOrPath !== plainName)
+        return urlOrPath;
+    return `${urlOrPath.slice(0, urlOrPath.length - plainName.length)}${hashedName}`;
+}
+/**
+ * Rewrite `plainUrl` (an absolute URL or path ending in the default
+ * bundle filename) to its content-hashed twin, hashing the bundle at
+ * `bundleFile` (default: the workspace's built bundle — the same file
+ * `createGguiServer` serves, so both stamp the same name). Falls back
+ * to `plainUrl` unchanged when the bundle is unreadable — the plain
+ * `no-cache` route always exists, so the fallback stays correct, just
+ * revalidated.
+ */
+export function resolveHashedRuntimeBundleUrl(plainUrl, bundleFile = RUNTIME_BUNDLE_FILE) {
+    let bytes;
+    try {
+        bytes = fs.readFileSync(bundleFile);
+    }
+    catch {
+        // Bundle not built / not shipped — mint the plain revalidated name.
+        return plainUrl;
+    }
+    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;
+    }
+}

package/dist/runtime-bundle-route.js

@@ -55,7 +55,7 @@ export function mountRuntimeBundleRoute(opts) {
             res.setHeader("Cache-Control", "no-cache");
             // CORS: the bundle MUST be loadable from `<script type="module"
             // src=...>` inside a sandboxed `srcdoc` iframe (the
-            // `<McpAppIframe>` mount path — see `packages/ggui-react/src/
+            // `<McpAppIframe>` mount path — see `packages/mcp-apps-react/src/
             // McpAppIframe/dispatch.ts::deriveResourceMountSource`). Such an
             // iframe has the `null` origin and module-script fetches always
             // run in CORS mode; without a permissive header browsers reject