@cloudgrid-io/mcp 0.21.10 → 0.21.12

package/README.md

@@ -84,7 +84,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 <!-- gen:tools -->
 ## Tools
 
-37 tools registered (15 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
+38 tools registered (16 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
 
 ### Direct-API tools (both editions)
 
@@ -105,6 +105,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 | `grid_start` | API | Orient before building with CloudGrid — the live runtime environment where the user's apps run WITH the infrastructur... |
 | `grid_get_template` | corpus | Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundle... |
 | `grid_report` | API | Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. |
+| `grid_hello` | API | Create a minimal hello page and plug it into the user's grid, returning the live URL. |
 
 The direct-API tools call the platform without the CLI, so they also work in
 the web edition. `grid_login` writes the same `~/.cloudgrid/credentials` the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.10",
+  "version": "0.21.12",
   "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": {
@@ -31,6 +31,8 @@
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
     "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:create-gates": "node test/create-gates.test.mjs",
+    "test:plug-create-grid-choice": "node test/plug-create-grid-choice.test.mjs",
+    "test:hello": "node test/hello.test.mjs",
     "test:grid-provisioning": "node test/grid-provisioning.test.mjs",
     "test:create-project-args": "node test/create-project-args.test.mjs",
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
@@ -70,6 +72,7 @@
     "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs",
     "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:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
     "test:internal-refs": "node --test test/no-internal-refs.test.mjs",
     "test:login-app": "node test/login-app.test.mjs",

package/src/oauth.js

@@ -228,11 +228,18 @@ export function mountOAuth(app, publicBase, opts = {}) {
     res.json({ resource: `${base}/mcp`, authorization_servers: [base], scopes_supported: ["cloudgrid"] });
   });
 
-  // RFC 8414.
-  app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+  // RFC 8414. Both the root form and the path-inserted form: the MCP
+  // authorization spec has clients derive the metadata URL from the RESOURCE
+  // url (…/mcp), so a client that tries `/.well-known/oauth-authorization-server/mcp`
+  // first must not get a 404 HTML page. The protected-resource document above
+  // already served both forms; this one served only the root, and the asymmetry
+  // was an oversight rather than a decision.
+  const serveAsMetadata = (_req, res) => {
     corsOk(res);
     res.json(asMetadata);
-  });
+  };
+  app.get("/.well-known/oauth-authorization-server", serveAsMetadata);
+  app.get("/.well-known/oauth-authorization-server/mcp", serveAsMetadata);
 
   // RFC 7591 — dynamic client registration. Public clients, PKCE-only.
   app.post("/oauth/register", (req, res) => {
@@ -319,6 +326,9 @@ export function mountOAuth(app, publicBase, opts = {}) {
         created: Date.now(),
       });
       authSessions.delete(String(req.query.sid));
+      // The sign-in half succeeded. Without this line a connector failure gives
+      // no way to tell whether the user ever got through sign-in at all.
+      console.error("[oauth] authorization code issued after sign-in; awaiting token exchange");
       const sep = sess.redirect_uri.includes("?") ? "&" : "?";
       const redirect = `${sess.redirect_uri}${sep}code=${encodeURIComponent(code)}${sess.state ? `&state=${encodeURIComponent(sess.state)}` : ""}`;
       res.json({ status: "ready", redirect });
@@ -332,22 +342,74 @@ export function mountOAuth(app, publicBase, opts = {}) {
   });
 
   // Token endpoint — PKCE-verified exchange; the CloudGrid JWT is the access token.
+  //
+  // WHY THIS BRANCHES INSTEAD OF ONE COMBINED `if`
+  //
+  // Reported 2026-08-30: ChatGPT web fails with "Something went wrong with
+  // setting up the connection" AFTER the user signs in, which puts the failure
+  // in this handler. It could not be diagnosed from either side, because five
+  // unrelated causes all produced a byte-identical `{"error":"invalid_grant"}`:
+  //
+  //   unknown/expired code · code already exchanged · client_id absent
+  //   · client_id mismatched · redirect_uri mismatched (a trailing slash does it)
+  //
+  // All five were reproduced against this handler (test/oauth-token-exchange).
+  // Nothing was logged, so the server could not say which happened either — the
+  // failure was invisible from both ends at once. That is the actual defect
+  // being fixed here: not the rejection, which is correct in every one of those
+  // cases, but that a rejection carried no information.
+  //
+  // The reason is logged server-side and returned as `error_description`. The
+  // caller already holds the code, the client_id and the redirect_uri it sent,
+  // so naming which of ITS OWN values did not match tells it nothing it did not
+  // already know. The token, the verifier and the code are never logged.
+  //
+  // THE TRADE, NAMED (so nobody extends this pattern by accident): branching
+  // these messages does hand a holder of an EXFILTRATED code a small oracle —
+  // they can confirm the code is live and probe client_id / redirect_uri
+  // without spending a PKCE guess. Accepted here because the code is
+  // single-use, dies in 5 minutes, and PKCE still gates the token, so the
+  // oracle reveals only values the attacker would have to have already; and
+  // RFC 6749 §5.2 explicitly provides error_description for this purpose. That
+  // reasoning is specific to this endpoint. Do NOT copy the pattern somewhere
+  // a failed attempt is cheap to repeat or the compared value is a secret.
+  const denyToken = (res, error, reason, detail = "") => {
+    console.error(`[oauth] token exchange refused: ${reason}${detail ? ` ${detail}` : ""}`);
+    res.status(400).json({ error, error_description: reason });
+  };
+
   app.post("/oauth/token", (req, res) => {
     corsOk(res);
     sweep(authCodes);
     const { grant_type, code, code_verifier, redirect_uri, client_id } = req.body ?? {};
     if (grant_type !== "authorization_code") {
-      res.status(400).json({ error: "unsupported_grant_type" });
+      denyToken(res, "unsupported_grant_type", "grant_type must be authorization_code", `(got ${JSON.stringify(grant_type ?? null)})`);
       return;
     }
     const rec = authCodes.get(String(code));
-    if (!rec || rec.client_id !== String(client_id) || rec.redirect_uri !== String(redirect_uri)) {
-      res.status(400).json({ error: "invalid_grant" });
+    if (!rec) {
+      // Also the retry case: codes are single-use, so a second exchange of a
+      // code that already succeeded lands here.
+      denyToken(res, "invalid_grant", "authorization code is unknown, expired or already exchanged");
+      return;
+    }
+    if (rec.client_id !== String(client_id)) {
+      denyToken(
+        res,
+        "invalid_grant",
+        client_id === undefined ? "client_id is required at the token endpoint" : "client_id does not match the one the code was issued to",
+      );
+      return;
+    }
+    if (rec.redirect_uri !== String(redirect_uri)) {
+      // The exact strings, because the difference is usually invisible —
+      // a trailing slash, a case change, an added query parameter.
+      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;
     }
     const challenge = b64url(createHash("sha256").update(String(code_verifier ?? "")).digest());
     if (challenge !== rec.code_challenge) {
-      res.status(400).json({ error: "invalid_grant", error_description: "PKCE verification failed." });
+      denyToken(res, "invalid_grant", code_verifier === undefined ? "code_verifier is required (PKCE)" : "PKCE verification failed");
       return;
     }
     authCodes.delete(String(code)); // single use

package/src/tools/deploy.js

@@ -104,7 +104,15 @@ export async function fetchUserOrgs(token) {
 //   - >1 grid and none supplied           → { picker } (a ready-to-return result)
 //   - exactly one grid                    → { single: annotatedOrg } — the caller
 //         decides how to treat a not-ready single grid (drop blocks; plug warns)
-//   - no orgs / listing failed            → { proceed: true } (fall through)
+//   - no orgs / listing failed            → { picker } needs_grid_create (asks)
+// Every return shape either ASKS (a picker) or names an explicit grid — none is a
+// silent proceed. That is load-bearing: register.js returns the picker or sets
+// input.grid from `grid`/`single` before runPlug, so the create path never
+// reaches runPlug's headerless fallback (#327). Do NOT reintroduce a
+// `{ proceed: true }` "fall through" shape here — a proceed with NO grid slips
+// past register.js without setting input.grid, into an ungated runPlug where
+// orgSlug is null and the SERVER picks the grid silently: exactly the wrong-grid
+// create this PR removed. A listing failure must ASK, never fall through.
 // User-facing text says "grid" (Gilad's org→grid rename); the structured payload
 // carries `needs_grid` AND the `needs_org`/`orgs`/`org`-slug fields the existing
 // org-picker web widget reads, so the web card keeps working. Stateless — no
@@ -1838,13 +1846,42 @@ export async function runPlug(ctx, input, deps = {}) {
     //      through — never a silent redirect.
     //   4. the target entity itself      — a pickup round-trip, only if 1–3 all
     //      came up empty. Reuse a pickup already done above to resolve the id.
-    orgSlug = grid || (await ctx.getActiveGrid());
-    if (!orgSlug) orgSlug = gridFromCloudgridUrl(targetUrl);
-    if (!orgSlug && isEdit) {
-      if (!pickupData && targetEntityId) {
-        pickupData = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+    if (isEdit) {
+      // EDIT: the destination is NOT ambiguous — the entity already lives in
+      // exactly one grid, so derive it (never ask). explicit `grid` → active
+      // grid → URL host → entity lookup (#296/#301/#316). This chain must stay
+      // intact: re-asking on every re-plug is noise and would undo those fixes.
+      orgSlug = grid || (await ctx.getActiveGrid());
+      if (!orgSlug) orgSlug = gridFromCloudgridUrl(targetUrl);
+      if (!orgSlug) {
+        if (!pickupData && targetEntityId) {
+          pickupData = await resolveEntityViaPickup(ctx, { target: targetEntityId });
+        }
+        if (pickupData?.grid) orgSlug = pickupData.grid;
       }
-      if (pickupData?.grid) orgSlug = pickupData.grid;
+    } else {
+      // CREATE (#327): the destination grid is the USER'S CHOICE and must be
+      // EXPLICIT — never silently reuse the persisted active grid. A stale
+      // active grid (weeks old, not surfaced to the user) silently lands a NEW
+      // entity in the wrong grid, and the grid decides the URL, who can open it
+      // (grid-scoped visibility), the datastore tier it inherits, and the
+      // namespace it runs in.
+      //
+      // What makes this safe is the grid-picker gate — resolveGridOrAsk (defined
+      // above; called from register.js): it either ASKS (returns a picker) or
+      // sets input.grid to an explicit slug (the single grid, or the user's
+      // choice) BEFORE runPlug runs. So on the real create path `grid` is always
+      // populated here.
+      //
+      // `null` is NOT a backstop — it is the DEFECT value. A headerless authed
+      // create does not refuse; it delegates the choice to the server, which
+      // resolves a default and picks a grid silently (the hosted half of this
+      // bug). The only reason a null is ever safe is that the gate above never
+      // lets an unresolved authed create reach here. Refusing on null (returning
+      // needs_grid instead of proceeding) is the stronger fix, tracked as a #327
+      // follow-up — do NOT rely on `orgSlug = grid || null` alone to prevent a
+      // wrong-grid create.
+      orgSlug = grid || null;
     }
     // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
     if (orgSlug) {

package/src/tools/register.js

@@ -61,6 +61,14 @@ export function buildCreateProjectArgs({ kind, name, type, needs, dir, grid, org
 // exclamation; say "plug" and "grid". The sign-in URL itself lands on its own
 // line later, from grid_login. No structural change — every caller still returns
 // { needs_auth: true }.
+// Escape untrusted text before it is interpolated into a page we publish at a
+// public URL. `&` MUST be replaced first, or the later replacements' own
+// ampersands get double-escaped. Both grid_hello sinks are element text
+// (<title> RCDATA and <body>), which this covers.
+const escapeHtml = (s) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+   .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
 const AUTH_ASK_SIGNED_OUT =
   "How would you like to plug this?\n" +
   "  - Sign in to your grid — it stays in your CloudGrid account.\n" +
@@ -396,9 +404,15 @@ export function registerTools(server, ctx) {
       "Re-plugging an anonymously-created drop needs its owner_token instead of sign-in.",
     ),
     grid: z.string().optional().describe(
-      "On create: the grid slug to plug into (omit to use the caller's active grid). On re-plug the entity " +
-      "never moves grids, but pass its home grid here when it differs from your active grid (the API " +
-      "checks your membership in the entity's grid). Anonymous → always the Guest grid.",
+      "On create: the grid slug to plug into. The destination grid is the USER'S CHOICE — treat it like " +
+      "visibility: NEVER infer one silently, and never reuse a previous or active grid without the user. If " +
+      "the user has more than one grid, CONFIRM which grid before plugging (omit this and grid_plug returns " +
+      "needs_grid with the grid list to choose from); a single-grid user is not asked. State the destination " +
+      "in the user's own terms (\"plugging into <grid>\") BEFORE the entity is created — a new entity in the " +
+      "wrong grid gets the wrong URL, is exposed to the wrong grid's members, and inherits the wrong datastore " +
+      "tier and namespace, and that is expensive to catch after the fact. On re-plug the entity never moves " +
+      "grids, but pass its home grid here when it differs from your active grid (the API checks your " +
+      "membership in the entity's grid). Anonymous → always the Guest grid.",
     ),
     slug: z.string().optional().describe(
       "Alternative RE-PLUG handle: paired with `grid`, resolves to an existing entity (the pickup " +
@@ -453,6 +467,10 @@ export function registerTools(server, ctx) {
         "Without target_entity_id: CREATE a new entity with a new URL. " +
         "With target_entity_id (or grid+slug): UPDATE the existing deployment IN PLACE, keeping the same URL — " +
         "this is the only deploy/publish tool, so do not look for a separate 'update' or 'redeploy' tool. " +
+        "GRID CHOICE (new plug): the destination grid is the user's choice, like visibility — do NOT infer or " +
+        "reuse a grid silently. For a user with more than one grid, CONFIRM which grid before plugging (omit " +
+        "`grid` and grid_plug returns needs_grid to ask); a single-grid user is not asked. State the " +
+        "destination before the entity is created. On re-plug the grid is fixed by the entity — never re-asked. " +
         "Sources (pass exactly one): `html` — a single self-contained HTML page (instant, any edition)" +
         (ctx.edition === "web"
           ? " or `artifact_files` — a multi-file app inline. "
@@ -1145,6 +1163,80 @@ export function registerTools(server, ctx) {
       }
     },
   );
+    // ── grid_hello — creates a hello page and plugs it (both editions) ────────
+  reg(
+    "grid_hello",
+    {
+      title: "Plug a hello page",
+      description:
+        "Create a minimal hello page and plug it into the user's grid, returning the live URL. " +
+        "If the user has more than one grid and `grid` is not given, this returns needs_grid with " +
+        "the list — ASK the user which grid, then call again with `grid` set. Never guess the grid. " +
+        "Requires sign-in.",
+      inputSchema: {
+        grid: z.string().optional()
+          .describe("Grid slug to plug into. Omit on the first call to be asked."),
+        name: z.string().optional()
+          .describe("Who to greet. Defaults to 'world'."),
+      },
+      outputSchema: {
+        url: z.string().optional().describe("The live URL, once plugged."),
+        entity_id: z.string().optional().describe("Re-plug handle."),
+        needs_auth: z.boolean().optional().describe("True when the user must sign in first."),
+        needs_grid: z.boolean().optional().describe("True when the user must choose a grid."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        // 1. AUTH — same shape as grid_plug (register.js:585). Not an error:
+        //    a result the model acts on by running grid_login.
+        const token = await ctx.getToken();
+        if (!token) {
+          // NOT the shared AUTH_ASK_SIGNED_OUT: that offers a guest path via
+          // `grid_plug` with anon:true, which this tool has no parameter for and
+          // which would send the model to a different tool with no source. Say
+          // only what grid_hello can actually do.
+          return okResult({
+            text:
+              "Plugging a hello page needs an account. Call grid_login to sign in, "
+              + "then re-call grid_hello.",
+            structured: { needs_auth: true },
+          });
+        }
+
+        // 2. GRID — never fall back to the active grid on a create (#327).
+        //    Four outcomes; three of them are handled right here.
+        const decision = await resolveGridOrAsk(ctx, {
+          token,
+          suppliedGrid: input?.grid,
+          edition: ctx.edition,
+        });
+        if (decision.picker) return okResult(decision.picker);   // >1 grid, or 0 grids → ASK
+        const grid = decision.grid || decision.single?.slug;     // matched, or exactly one
+        if (!grid) return fail("Could not resolve a grid. Pass `grid` explicitly.");
+
+        // 3. BUILD — escape user input. This page is published to a public URL.
+        const who = escapeHtml(String(input?.name ?? "world").slice(0, 60));
+        const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Hello, ${who}</title>
+<style>
+  body{margin:0;height:100vh;display:grid;place-items:center;
+       font:600 clamp(2rem,10vw,6rem)/1.1 ui-sans-serif,system-ui,sans-serif;
+       background:#0b0b0f;color:#f4f4f5}
+</style></head>
+<body>Hello, ${who}</body></html>`;
+
+        // 4. PLUG — one inline HTML document is an inspiration. runPlug does the rest.
+        const res = await runPlug(ctx, { html, grid });
+        return okResult(res);
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
 
   if (ctx.edition !== "local") return; // web edition stops here — no CLI tools