@cloudgrid-io/mcp 0.21.15 → 0.21.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.15",
+  "version": "0.21.17",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -74,6 +74,7 @@
     "test:web-restart-recovery": "node --test test/web-restart-recovery.test.mjs",
     "test:oauth-client-persistence": "node --test test/oauth-client-persistence.test.mjs",
     "test:oauth-token-exchange": "node --test test/oauth-token-exchange.test.mjs",
+    "test:oauth-resource-indicators": "node --test test/oauth-resource-indicators.test.mjs",
     "test:oauth-observability": "node --test test/oauth-flow-observability.test.mjs",
     "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
     "test:mcp-transport-observability": "node --test test/mcp-transport-observability.test.mjs",

package/src/oauth.js

@@ -21,8 +21,8 @@ const CODE_TTL_MS = 5 * 60 * 1000; // authorize sessions + auth codes live 5 min
 // are 5-minute, retry-on-failure sessions: losing them to a restart just means
 // the user clicks "sign in" again, never that they must re-add the connector.
 // Client REGISTRATIONS are NOT here — they are stateless (see below, #3060).
-const authSessions = new Map(); // sid -> { cgCode, client_id, redirect_uri, state, code_challenge, created }
-const authCodes = new Map(); // code -> { jwt, client_id, redirect_uri, code_challenge, created }
+const authSessions = new Map(); // sid -> { cgCode, client_id, redirect_uri, state, code_challenge, resource, created }
+const authCodes = new Map(); // code -> { jwt, client_id, redirect_uri, code_challenge, resource, created }
 
 function sweep(map) {
   const now = Date.now();
@@ -58,6 +58,38 @@ function hostOf(uri) {
   }
 }
 
+// --- RFC 8707 Resource Indicators (#329) --------------------------------------
+// The MCP 2025-06-18 authorization spec has clients send `resource` — the
+// canonical URI of the MCP server the token is for — on BOTH the authorize and
+// token requests. We accept it, validate it against this server's own resource
+// identifier (the `${base}/mcp` value /.well-known/oauth-protected-resource
+// returns), and bind it to the code. A mismatch is `invalid_target` (RFC 8707
+// §2). A MISSING resource stays acceptable: Claude web / Claude Code work today
+// and may not send it, and the spec is explicit that clients "MUST send this
+// parameter regardless of whether authorization servers support it" — i.e. the
+// server may still honour requests without it.
+//
+// Comparison is on the CANONICAL form, not a raw string, so a cosmetically
+// different but equivalent URI (uppercase scheme/host, a trailing slash, a
+// default port) is not falsely rejected. Per the spec: lowercase scheme and
+// host (URL parsing does this), no fragment, and the trailing-slash-free path.
+// The QUERY STRING is also dropped by construction (we rebuild from protocol +
+// host + path only), so `…/mcp?x=1` compares EQUAL to `…/mcp`. That is the
+// permissive direction and fine here — our resource identifier carries no
+// query — but it is stated because nobody would predict it from the code.
+// Returns null for anything that is not an absolute URI — that then fails the
+// equality check as a mismatch.
+function normalizeResource(uri) {
+  try {
+    const u = new URL(String(uri));
+    if (!u.host) return null;
+    const path = u.pathname.replace(/\/+$/, ""); // …/mcp/ ≡ …/mcp
+    return `${u.protocol}//${u.host}${path}`; // protocol + host are already lowercased & default-port-stripped
+  } catch {
+    return null;
+  }
+}
+
 // --- Stateless client registration (#3060) -----------------------------------
 // A `client_id` is a signed token that CARRIES its own redirect-URI set, not a
 // random handle into a process-local Map. Registration signs the (sorted,
@@ -198,6 +230,10 @@ function interstitialHtml(sid, loginUrl) {
 export function mountOAuth(app, publicBase, opts = {}) {
   if (!opts.requireAuth) return;
   const base = publicBase.replace(/\/+$/, "");
+  // This server's resource identifier — the exact value the protected-resource
+  // metadata returns and the canonical `resource` a client must send (#329).
+  const resourceId = `${base}/mcp`;
+  const expectedResource = normalizeResource(resourceId);
 
   // Resolve the client-registration signing secret(s) once at mount. Log which
   // mode is active — durable vs. ephemeral — so a production deploy can be
@@ -236,6 +272,14 @@ export function mountOAuth(app, publicBase, opts = {}) {
     code_challenge_methods_supported: ["S256"],
     token_endpoint_auth_methods_supported: ["none"],
     scopes_supported: ["cloudgrid"],
+    // RFC 8707 Resource Indicators support (#329). RFC 8707 defines NO
+    // authorization-server metadata field of its own, and neither does the MCP
+    // spec; the only IANA-registered resource-related AS-metadata field is
+    // `protected_resources` (RFC 9728 §4) — a JSON array of the resource
+    // identifiers this AS issues tokens for. Advertising ours here lets a client
+    // discover the canonical `resource` value to send, and signals that we honour
+    // the parameter rather than ignoring it.
+    protected_resources: [resourceId],
   };
 
   app.options(/^\/(\.well-known|oauth)\/.*/, (_req, res) => {
@@ -302,16 +346,19 @@ export function mountOAuth(app, publicBase, opts = {}) {
   // Authorization endpoint — render the bridge interstitial.
   app.get("/oauth/authorize", (req, res) => {
     sweep(authSessions);
-    const { client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type } = req.query;
-    // Observability (#345): the request SHAPE the client actually sent, logged
-    // before any check so a rejected request is still visible. Presence, not
-    // values — nothing here is reusable in a log aggregator.
+    const { client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type, resource } = req.query;
+    // Observability (#345/#329): the request SHAPE the client actually sent,
+    // logged before any check so a rejected request is still visible. Presence,
+    // not values — nothing here is reusable in a log aggregator. The resource
+    // HOST is included: it is not a secret, and its presence/absence is the exact
+    // signal that distinguishes ChatGPT (sends it) from Claude (does not).
     console.error(
       `[oauth] authorize request: client_id=${clientIdPrefix(client_id)} ` +
         `response_type=${response_type ? String(response_type) : "absent"} ` +
         `state=${state ? "present" : "absent"} ` +
         `pkce=${code_challenge ? (code_challenge_method ? String(code_challenge_method) : "present(no-method)") : "absent"} ` +
-        `redirect_host=${hostOf(redirect_uri)}`,
+        `redirect_host=${hostOf(redirect_uri)} ` +
+        `resource_host=${hostOf(resource)}`,
     );
     const client = verifyClientId(client_id, clientSecrets.secrets);
     if (!client || !client.redirect_uris.includes(String(redirect_uri))) {
@@ -322,6 +369,39 @@ export function mountOAuth(app, publicBase, opts = {}) {
       res.status(400).send("This server requires response_type=code with PKCE (S256).");
       return;
     }
+    // RFC 8707 (#329): if a `resource` is present it must be THIS server's
+    // resource identifier. Compared on the canonical form so an equivalent URI
+    // (case, trailing slash, default port) is accepted. A mismatch is
+    // invalid_target; a MISSING resource stays acceptable (Claude compatibility).
+    // The bound value is the canonical string, so the token endpoint can compare
+    // apples to apples later.
+    let boundResource = "";
+    if (resource !== undefined && String(resource) !== "") {
+      const requested = normalizeResource(resource);
+      if (!requested || requested !== expectedResource) {
+        // RFC 6749 §4.1.2.1: the redirect_uri is already verified as registered
+        // (the render-path 400 above), so an authorization error is returned by
+        // REDIRECTING to it with error= and state=, NOT by rendering an opaque
+        // body the client cannot read — RFC 8707 §2 defines invalid_target as
+        // exactly such an OAuth error code. This is the whole point of the PR:
+        // a spec fix that makes a silent failure legible must not add a new
+        // illegible one (an opaque 400 where ChatGPT expects
+        // error=invalid_target&state=… would just be another #329-shaped
+        // symptom). The two 400s above STAY renders: an unverified client or
+        // redirect_uri must NEVER be redirected to, so they are not precedent.
+        console.error(
+          `[oauth] authorize refused (redirect): invalid_target resource_host=${hostOf(resource)} expected_host=${hostOf(resourceId)}`,
+        );
+        const sep = String(redirect_uri).includes("?") ? "&" : "?";
+        let location = `${redirect_uri}${sep}error=invalid_target&error_description=${encodeURIComponent(
+          "The requested resource does not identify this server.",
+        )}`;
+        if (state) location += `&state=${encodeURIComponent(String(state))}`;
+        res.redirect(302, location);
+        return;
+      }
+      boundResource = requested;
+    }
     const sid = randomUUID();
     const cgCode = newLoginCode();
     authSessions.set(sid, {
@@ -330,6 +410,7 @@ export function mountOAuth(app, publicBase, opts = {}) {
       redirect_uri: String(redirect_uri),
       state: state ? String(state) : "",
       code_challenge: String(code_challenge),
+      resource: boundResource,
       created: Date.now(),
     });
     res.setHeader("Content-Type", "text/html; charset=utf-8");
@@ -358,6 +439,7 @@ export function mountOAuth(app, publicBase, opts = {}) {
         client_id: sess.client_id,
         redirect_uri: sess.redirect_uri,
         code_challenge: sess.code_challenge,
+        resource: sess.resource, // RFC 8707 binding carried from the authorize session (#329)
         created: Date.now(),
       });
       authSessions.delete(String(req.query.sid));
@@ -420,7 +502,7 @@ export function mountOAuth(app, publicBase, opts = {}) {
   app.post("/oauth/token", (req, res) => {
     corsOk(res);
     sweep(authCodes);
-    const { grant_type, code, code_verifier, redirect_uri, client_id } = req.body ?? {};
+    const { grant_type, code, code_verifier, redirect_uri, client_id, resource } = req.body ?? {};
     if (grant_type !== "authorization_code") {
       denyToken(res, "unsupported_grant_type", "grant_type must be authorization_code", `(got ${JSON.stringify(grant_type ?? null)})`);
       return;
@@ -448,6 +530,23 @@ export function mountOAuth(app, publicBase, opts = {}) {
       denyToken(res, "invalid_grant", "redirect_uri does not match the authorize request", `(sent ${JSON.stringify(redirect_uri ?? null)}, expected ${JSON.stringify(rec.redirect_uri)})`);
       return;
     }
+    // RFC 8707 (#329): if the client repeats `resource` at the token endpoint it
+    // must be the one bound at authorize. Mismatch → invalid_target, refused via
+    // denyToken so it is logged. A token request with NO resource stays
+    // acceptable (Claude compatibility), even when one was bound. Only the HOSTS
+    // are logged — the resource URI is not a secret but nothing bearer-shaped is.
+    if (resource !== undefined && String(resource) !== "") {
+      const requested = normalizeResource(resource);
+      if (!requested || requested !== rec.resource) {
+        denyToken(
+          res,
+          "invalid_target",
+          "resource does not match the authorize request",
+          `(resource_host ${hostOf(resource)} vs bound ${hostOf(rec.resource)})`,
+        );
+        return;
+      }
+    }
     const challenge = b64url(createHash("sha256").update(String(code_verifier ?? "")).digest());
     if (challenge !== rec.code_challenge) {
       denyToken(res, "invalid_grant", code_verifier === undefined ? "code_verifier is required (PKCE)" : "PKCE verification failed");

package/src/tools/constants.js

@@ -64,25 +64,36 @@ export const VISIBILITY_LABELS = {
 // the widget HTML is verified to render. The resources stay registered either
 // way (harmless when no tool references them via outputTemplate).
 //
-// 2026-08-25 (#308): the black frame was diagnosed as a MIME mismatch. ChatGPT
-// discovers an Apps-SDK widget by a tool carrying openai/outputTemplate PLUS a
-// ui:// resource whose mimeType is `text/html+skybridge` (verified against
-// OpenAI's shipped example servers — openai/openai-apps-sdk-examples
-// solar-system/shopping_cart/kitchen_sink main.py). Our two ChatGPT widgets
-// declared `text/html;profile=mcp-app` — the SEP-1865/MCP-Apps MIME that CLAUDE
-// reads (RESOURCE_MIME_TYPE in @modelcontextprotocol/ext-apps). ChatGPT saw the
-// outputTemplate pointer, opened the skybridge iframe (dark chrome), but the
-// resource was not a skybridge document, so the HTML/bridge never populated —
-// the empty dark frame covering the text. CHATGPT_WIDGET_MIME below is the
-// correct type. The flag STAYS OFF until a card is seen rendering in real
-// ChatGPT (Developer Mode custom connector against staging); this only makes the
-// machinery correct for that verification.
+// 2026-08-31 (#308, corrected): the widgets targeted a RETIRED MIME. At DevDay
+// (Oct 2025) ChatGPT's Apps SDK used `text/html+skybridge`, and #309 switched us
+// to it. But the Apps SDK merged with MCP Apps into SEP-1865, ratified
+// 2026-01-26, and OpenAI's CURRENT docs (developers.openai.com/apps-sdk
+// build/custom-ux, deploy/troubleshooting) now specify `text/html;profile=mcp-app`
+// — the same MIME Claude reads. skybridge is not mentioned anywhere in the
+// current docs. So ChatGPT opened the iframe on our skybridge resource, could not
+// recognise it, and never populated it — the empty frame over the text.
+//
+// The clincher: our own Claude sign-in card (#303) RENDERS, and it declares
+// `text/html;profile=mcp-app`. The MIME that renders is the standard one; the one
+// that does not is skybridge. The two hosts converged; the old separation was the
+// defect. CHATGPT_WIDGET_MIME below now equals RESOURCE_MIME_TYPE by value. The
+// widget bridge (window.openai.toolOutput / openExternal / callTool /
+// ui/notifications/tool-result) is already current — verified against
+// developers.openai.com/apps-sdk/reference — so only the MIME changes.
+//
+// The flag stays where the platform sets it; this only makes the resource the
+// type ChatGPT now expects. Done is a card seen rendering in real ChatGPT.
 export const APPS_WIDGETS_ENABLED = process.env.MCP_APPS_WIDGETS === "1";
 // The mimeType ChatGPT's Apps-SDK renderer requires for a ui:// widget resource.
-// Distinct from RESOURCE_MIME_TYPE (`text/html;profile=mcp-app`, the SEP-1865
-// key Claude reads) — the two hosts key off different MIME types, so the ChatGPT
-// widgets and the Claude sign-in card must NOT share one.
-export const CHATGPT_WIDGET_MIME = "text/html+skybridge";
+// Since SEP-1865 (2026-01-26) this EQUALS RESOURCE_MIME_TYPE (`text/html;profile=
+// mcp-app`): both hosts now render the standard MCP-Apps MIME. Both hosts also
+// read the SAME binding key, `_meta.ui.resourceUri`; ChatGPT honors
+// `openai/outputTemplate` only as a compatibility alias (OpenAI's own
+// deploy/troubleshooting page). So our two mechanisms stay separate not because
+// the hosts key off different MIMEs or different keys, but because WE bind them
+// on different keys: the ChatGPT widget via `openai/outputTemplate` (the alias,
+// which Claude ignores), the Claude card via `_meta.ui.resourceUri`.
+export const CHATGPT_WIDGET_MIME = "text/html;profile=mcp-app";
 export const LIVE_RESULT_URI = "ui://cloudgrid/live-result.html";
 // URI/resource-name/filename stay `org-picker` — that's the stable contract the
 // web card is registered under; only the JS identifier moves toward grid.

package/src/tools/deploy.js

@@ -2382,15 +2382,16 @@ export async function runPlug(ctx, input, deps = {}) {
   // /grids/<slug> form 404s; /home?grid= does not. Falls back to the root when
   // the slug is unknown.
   //
-  // NOT on the building branch: the line says "view it live", and a still-building
-  // app is not live — emitting it two lines under "Do NOT tell the user it is live"
-  // would hand a model the word "live" next to a pending app. For an async runtime
-  // build the console line arrives when liveness is confirmed, in runCheckDeploy's
-  // success branch.
+  // NOT on the building branch. This line invites the user to "see and manage all
+  // their apps in their grid" — an invitation that presumes the app is live. A
+  // still-building app is not, and it sits two lines under "Do NOT tell the user it
+  // is live", so relaying a manage-your-apps prompt there contradicts the honesty
+  // gate. For an async runtime build the console line arrives once liveness is
+  // confirmed, in runCheckDeploy's success branch.
   if (data.entity_id && !isBuilding) {
     const consoleUrl = consoleGridUrl(data.grid ?? grid ?? null);
     structured.console_url = consoleUrl;
-    lines.push(`You can view it live in your grid along with all the apps you build here: ${consoleUrl}`);
+    lines.push(`Give the user this link so they can see and manage all their apps in their grid: ${consoleUrl}`);
   }
 
   // Visibility is the user's choice — never set silently. On a NEW deploy,
@@ -2881,9 +2882,10 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
     return {
       // The "now live" moment for an async runtime build lands here, not in
       // runPlug (which returned "building"). Point the user at their grid too
-      // (#321) — this is where liveness is confirmed, so "view it live" is true.
+      // (#321) — this is where liveness is confirmed, so the manage-your-apps
+      // invitation is honest to make.
       text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.\n` +
-        `You can view it live in your grid along with all the apps you build here: ${consoleGridUrl(gridSlug)}`,
+        `Give the user this link so they can see and manage all their apps in their grid: ${consoleGridUrl(gridSlug)}`,
       structured: { status: "success", live: true, ...(url ? { url } : {}), console_url: consoleGridUrl(gridSlug) },
     };
   }

package/src/tools/register.js

@@ -133,9 +133,10 @@ export function registerTools(server, ctx) {
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
   if (ctx.edition === "web") {
-    // ChatGPT Apps-SDK widgets. mimeType MUST be text/html+skybridge
-    // (CHATGPT_WIDGET_MIME) — NOT the MCP-Apps `text/html;profile=mcp-app` the
-    // Claude card uses; that mismatch was the black frame (#308). widgetAccessible
+    // ChatGPT Apps-SDK widgets. mimeType is CHATGPT_WIDGET_MIME, which since
+    // SEP-1865 (2026-01-26) IS `text/html;profile=mcp-app` — the standard MCP-Apps
+    // type. The old `text/html+skybridge` was retired and was the black frame
+    // (#308); the hosts stay separated by binding, not MIME. widgetAccessible
     // lets the widget call tools back over window.openai.callTool (the visibility
     // pills call grid_visibility). These make no direct network requests, so no
     // openai/widgetCSP is declared — the default deny is correct.
@@ -538,11 +539,12 @@ export function registerTools(server, ctx) {
       // live at a public URL in place. Versions + grid rollback exist, but the
       // honest MCP annotation for overwrite-live-state is destructive.
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-      // ChatGPT-only binding: openai/outputTemplate points at the skybridge
-      // widget. Deliberately NOT the MCP-Apps `ui.resourceUri` key — that is
-      // Claude's, and the live-result resource is now text/html+skybridge, which
-      // Claude cannot render; carrying it here would regress the Claude path when
-      // this flag is flipped. The two mechanisms stay independent (#308/#303).
+      // Bound via openai/outputTemplate, which ChatGPT honors as a compatibility
+      // alias for `_meta.ui.resourceUri` and which Claude ignores — so this
+      // widget renders in ChatGPT only. Deliberately NOT `_meta.ui.resourceUri`:
+      // since SEP-1865 both hosts read THAT key, so binding there would render the
+      // widget in Claude too. The two mechanisms stay independent because they
+      // bind on different keys, not different MIMEs (#308/#303).
       ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
         _meta: { "openai/outputTemplate": LIVE_RESULT_URI },
       } : {}),
@@ -717,10 +719,11 @@ export function registerTools(server, ctx) {
         login_url: z.string().describe("URL to open in a browser to complete sign-in."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-      // Bind the SEP-1865 sign-in card on the web edition (Claude web). This is
-      // the SEP-1865 key (_meta.ui.resourceUri); ChatGPT reads openai/outputTemplate
-      // and ignores it, and a client without the UI extension ignores it too and
-      // gets the text-first result below. NOT gated behind MCP_APPS_WIDGETS — a
+      // Bind the SEP-1865 sign-in card on the web edition (Claude web) via the
+      // standard `_meta.ui.resourceUri` key. It carries NO openai/outputTemplate
+      // and is not gated by MCP_APPS_WIDGETS, so it is the Claude sign-in card;
+      // a client without the UI extension ignores _meta.ui and gets the
+      // text-first result below. NOT gated behind MCP_APPS_WIDGETS — a
       // second, independent mechanism (see constants.js). The result shape is
       // unchanged: content[0] stays the sign-in URL text so the link is never
       // unreachable if the card does not render.
@@ -865,7 +868,7 @@ export function registerTools(server, ctx) {
         status: z.string().describe("The build status: success | failed | building | queued | unknown."),
         live: z.boolean().describe("True only when the build finished successfully and the URL serves."),
         url: z.string().optional().describe("The live URL, when known."),
-        console_url: z.string().optional().describe("On success: URL to view the app live in the grid alongside all the user's apps."),
+        console_url: z.string().optional().describe("On success: a link to see and manage all the apps in the grid, in the console."),
         error: z.string().optional().describe("User-language failure reason, when the build failed."),
         build_log_tail: z.string().optional().describe("Sanitized tail of the Cloud Build log (the real error), when the build failed."),
         suggested_fix: z.string().optional().describe("A suggested fix for the failure, when the platform provides one."),
@@ -1194,6 +1197,13 @@ export function registerTools(server, ctx) {
         error: z.boolean().optional().describe("True when the grid listing failed (network/auth error). The text carries a human-readable message. Do NOT treat this as needs_grid_create."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // ChatGPT Apps-SDK card, same binding as grid_plug: grid_hello returns a
+      // runPlug result, so it deserves the same live-result widget. Without this a
+      // grid_hello success renders no card even when the MIME is correct (#308).
+      // openai/outputTemplate is ChatGPT-only; Claude ignores it, so #303 is safe.
+      ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
+        _meta: { "openai/outputTemplate": LIVE_RESULT_URI },
+      } : {}),
     },
     async (input) => {
       try {