@groundfloorcloud/mcp 0.2.3 → 0.2.4

package/README.md

@@ -82,7 +82,7 @@ Use the prefixed names: `GROUNDFLOOR_API_URL`, `GROUNDFLOOR_WORKSPACE_ID`, `GROU
 | `secrets_list` / `files_list` / `dataplane_status` | Inspect (no secrets values) |
 | `domains_list` | Custom domains of an App's Coderunner (`app_id` or `coderunner_id`). Domains exist on Apps, not standalone Coderunners |
 | `quota_get` / `billing_summary` | Plan quota and billing for the workspace's **account** (account id is not the workspace id; billing needs organization Owner, Admin or Billing admin) |
-| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
+| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication`, `service-access` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
 | `suggest_cli` | Command to run: login, deploy, create_app, init_app, publish_app, m2m_token, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.

package/dist/index.js

@@ -627,8 +627,12 @@ with no role at all gets 403 too.
 ## In a Shell app
 
 The signed-in user's JWT comes from \`window.__GF_GET_ACCESS_TOKEN__()\`. See
-\`docs_get\` id \`shell\`. Unattended workloads use M2M instead (\`docs_get\` id
-\`m2m\`), not an end-user login.
+\`docs_get\` id \`shell\`. Roles are in the token's \`realm_access.roles\`
+(Groundfloor mode). A Shell app's backend Service is public and must verify
+that token itself (issuer and client ID from \`/v1/public/workspaces/by-host\`,
+JWKS, RS256): \`docs_get\` id \`service-access\`.
+Unattended workloads use M2M instead (\`docs_get\` id \`m2m\`), not an
+end-user login.
 `.trim();
 
 // src/coderunner-runtime.ts
@@ -868,6 +872,11 @@ CMD ["npm", "start"]
 
 - Services follow the \`npm start\` / \`PORT\` contract: Node needs \`scripts.start\` if CMD is \`npm start\`.
 - Prefer curling the Deployment URL (\`/health\`) over \`\u2026/run\`.
+- **The Deployment URL (and any App domain on it) is public.** Groundfloor
+  checks no identity. A Service that is a Shell app's backend must verify the
+  user's token itself, and allow the Shell origin for CORS. Off-the-shelf
+  images (port 80 defaults, MySQL, local uploads, sessions): \`docs_get\` id
+  \`service-access\`.
 
 ## Latest deploy rules (all types)
 
@@ -965,10 +974,14 @@ An M2M client can also read secret **values** directly at runtime instead
 of (or alongside) \`--secret\` deploy-time injection: grant it the
 **\`secrets:read\`** scope (same Portal **Administer \u2192 M2M tokens** screen,
 per-client toggle), then call
-\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}\` with
-\`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
+\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}?environment_id=$GROUNDFLOOR_ENVIRONMENT_ID\`
+with \`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
 workload's injected \`GROUNDFLOOR_M2M_CLIENT_ID\`/\`GROUNDFLOOR_M2M_CLIENT_SECRET\`
-exchanged the same way. This path is:
+exchanged the same way. **Always pass \`environment_id\`**
+(\`GROUNDFLOOR_ENVIRONMENT_ID\` is injected on deploy for a Coderunner bound to
+an environment) to choose which environment's value is read: omitted or
+empty, it resolves to the workspace's \`dev\` environment (or its only active
+one), so a prod workload silently reads dev secrets. This path is:
 
 - **Read-only** \u2014 \`secrets:read\` never grants \`upsert\`/\`delete\`, regardless
   of the client's writer relation on Vault/Files.
@@ -977,7 +990,9 @@ exchanged the same way. This path is:
 - **Workspace-wide, not per-key or per-environment** \u2014 granting the scope
   exposes every secret in the workspace across all environments to that
   client's code, same class of trade as the existing Vault/Files writer
-  grant. Not a fit for isolating one secret to one Coderunner.
+  grant. \`environment_id\` only selects which environment's value is
+  returned; it is not an access boundary. Not a fit for isolating one secret
+  (or one environment) to one Coderunner.
 
 Prefer it over \`--secret\` injection when you want live rotation and can
 do the fetch yourself; keep using \`--secret\` injection for SDKs that only
@@ -1258,6 +1273,113 @@ active environments \xB7 400 bad or reserved key \xB7 422 value/value_type misma
 423 workspace frozen (writes).
 `.trim();
 
+// src/service-access-guide.ts
+var SERVICE_ACCESS_GUIDE = `
+# Who can reach a Service (and checking Shell tokens in a backend)
+
+## The rule
+
+Every Coderunner Service is public. Its Deployment URL, and an App's domain
+routed to it, accept requests from anyone. Groundfloor routes the request but
+signs nobody in and checks no token. The Service decides who gets in.
+
+| Service is\u2026 | Example | Do |
+|---|---|---|
+| Open to everyone | website, docs, public API, webhook receiver | Nothing (default) |
+| An app with its own logins | WordPress, Ghost, Metabase | Nothing from Groundfloor; its own login applies. Admin pages (\`/wp-admin\`) are public too |
+| Backend for a Shell app | API the Shell app calls with \`__GF_GET_ACCESS_TOKEN__()\` | Verify the user's token on **every** request |
+
+Never tell a user that Shell sign-in, App authentication or Site access
+protects a Service. Anyone can call the Service directly.
+
+## Verifying a Shell user's token in a backend
+
+1. **Issuer and client ID**: \`GET {CONTROLPLANE_URL}/v1/public/workspaces/by-host?host=<shell-site-host>\`
+   (unauthenticated) \u2192 \`{ workspace_id, mode, oidc: { issuer, client_id } | null, site_host }\`.
+   Check \`workspace_id\` is the user's workspace. \`oidc\` is null in mode
+   \`none\`. Groundfloor mode: per-workspace issuer, \`client_id\` \`shell\`.
+   External mode: the provider's issuer and the client ID the customer
+   entered. Look it up **once at setup**, never at runtime from the request's
+   \`Host\` header (caller-controlled). Do not hard-code the issuer host (it
+   differs per cell); copy the issuer **exactly, including any trailing \`/\`**
+   (do not strip it before comparing \`iss\`) into non-secret env such as
+   \`AUTH_ISSUER\` / \`AUTH_CLIENT_ID\` (Dockerfile \`ENV\`, since deploy-time
+   env is not kept between deploys).
+2. **Checks** (401 if any fails): RS256 signature against
+   \`{issuer}/protocol/openid-connect/certs\` (External: the provider's
+   \`jwks_uri\`), key chosen by the token's \`kid\` (the JWKS has several
+   keys); \`iss\` equals the issuer exactly; \`exp\` present and in the future;
+   the token was issued to the client ID:
+   - Groundfloor mode: \`azp\` == client ID. Do not require an app-specific
+     \`aud\` (none exists yet; tokens often carry \`aud: "account"\`, so with
+     PyJWT set \`verify_aud: False\` and check the client yourself).
+   - External mode: the client ID must appear in \`azp\` (or the provider's
+     equivalent, e.g. \`cid\`, \`appid\`) **or** in \`aud\`. Never accept a
+     token naming it in neither. If the provider allows open sign-up, "any
+     signed-in user" means anyone: require a role.
+   403 when the token is valid but the role (or tenant) is wrong.
+3. **Claims**: roles in \`realm_access.roles\` (built-in \`viewer\`/\`user\`/
+   \`admin\` plus custom roles; ignore \`offline_access\`, \`uma_authorization\`,
+   \`default-roles-*\`). Treat a missing or malformed \`realm_access\`/\`roles\`
+   (not an object / not a list) as no roles \u2192 403, never a 500, and match
+   whole role strings only. External mode: roles come from the customer's
+   provider, in its own claim. For the user ID claim, follow the docs page
+   /docs/apps/shell/sign-in#know-who-the-user-is.
+   **Multi-tenant**: roles apply across every company (an \`admin\` in one
+   company is admin everywhere), so filter every read and write by the
+   \`organization\` claim too. It can hold more than one company: check the
+   record's company is in it. Its exact form is unconfirmed; accept a list of
+   names or an object keyed by name, anything else = no companies.
+4. **Libraries**: Python PyJWT \`PyJWKClient(JWKS_URL, timeout=5)\` (it
+   refetches the JWKS on every unknown \`kid\`, so keep the timeout short) +
+   \`jwt.decode(token, key.key, algorithms=["RS256"], issuer=ISSUER,
+   options={"require": ["exp", "iss"], "verify_aud": False})\`, then
+   \`azp == CLIENT_ID\` (External: or \`cid\`/\`appid\`/\`aud\`), as a FastAPI
+   dependency plus a \`require_role()\` dependency for 403. Node: \`jose\`
+   \`createRemoteJWKSet\` + \`jwtVerify(token, JWKS, { issuer, algorithms:
+   ["RS256"], requiredClaims: ["exp"] })\`, then the same client check; fail at
+   startup if \`AUTH_ISSUER\` or \`AUTH_CLIENT_ID\` is unset (an undefined
+   issuer disables jose's \`iss\` check). Full examples on the docs page.
+5. **CORS**: the Shell site and the Service are different origins, so the
+   browser preflights calls carrying \`Authorization\`. Allow the Shell site
+   origin (and its custom domain), methods, and the \`Authorization\` and
+   \`Content-Type\` headers (FastAPI \`CORSMiddleware\`; Express
+   \`cors({ origin: ["https://<shell-site>"], allowedHeaders: ["Authorization", "Content-Type"] })\`,
+   never bare \`cors()\`, which allows every origin), so preflight is answered
+   before the token check. Never \`*\` with credentials; the bearer header
+   needs no credentials mode.
+
+## Every app on the Shell site can use the user's token
+
+Every app on a Shell site, including apps the customer didn't write, can get
+the signed-in user's token and call the customer's backends as that user, and
+a token from one app is accepted by every other app's backend in the
+workspace. Tell users to install only apps they trust and to check roles for
+anything sensitive. Per-app tokens, sign-in settings injected into the
+Service, and a verify helper are planned (no date). Do not promise per-app
+isolation.
+
+## Running off-the-shelf images as a Service
+
+- Listen on 8080 (or \`PORT\`) on 0.0.0.0; many images default to 80, so
+  reconfigure in the Dockerfile.
+- Managed databases are PostgreSQL only; MySQL/MariaDB/MongoDB apps
+  (WordPress) need an external database.
+- **Finish the installer immediately**: apps with a first-visit installer
+  (WordPress) can be claimed by anyone who opens the URL until it's completed.
+  Tell the user to complete it as soon as the first deploy finishes.
+- Read secrets in an entrypoint script: pass the M2M credentials to curl on
+  stdin (not argv), fail closed if the value is empty, \`unset\` the M2M
+  credentials and token before \`exec\`ing the app.
+- Local disk is lost on restart, redeploy and scale-to-zero, and is per
+  instance. Use the app's S3/object-storage plugin against external storage;
+  Groundfloor Files is an API for code the customer writes, not an S3 endpoint.
+- More than one instance breaks in-memory/on-disk sessions; keep one instance
+  or store sessions in the database. Set min instances \u2265 1 so the first visit
+  doesn't wait.
+- Only the app's own login applies; Groundfloor sign-in can't front it today.
+`.trim();
+
 // src/shell-guide.ts
 var SHELL_APP_GUIDE = `
 # Shell federated apps
@@ -1305,6 +1427,12 @@ outside Shell) so the breadcrumb does not show the raw id. Give that route
 routes (omit it or use \`false\` otherwise \u2014 never \`null\`). \`visibility:
 "public"\` makes a route reachable without login.
 
+Backends: secrets and server-side work go in a Coderunner Service the app
+calls with \`Authorization: Bearer \${await window.__GF_GET_ACCESS_TOKEN__()}\`.
+Shell sign-in does **not** protect that Service: its URL is public, so it must
+verify the token on every request and allow the Shell origin for CORS
+(\`docs_get\` id \`service-access\`).
+
 ## suggest_cli
 
 - create_app \u2192 \`gf apps create --name "<App Name>" --slug <portal-slug> --kind shell_federated\` (register the App first; publish fails with App not found otherwise)
@@ -1513,6 +1641,14 @@ var DOC_CATALOG = [
     embedded: CODERUNNER_RUNTIME_CONTRACT,
     lastUpdated: "2026-10-08"
   },
+  {
+    id: "service-access",
+    title: "Who can reach your Service",
+    path: "/docs/deploy/securing-a-service",
+    summary: "Every Service (Deployment URL or App domain) is public; Groundfloor signs nobody in and checks no token. Open sites and apps with their own logins need nothing (finish installers like WordPress immediately); a Shell app's backend must verify the user's JWT on every request: issuer and client_id copied once from GET /v1/public/workspaces/by-host (never from the request Host header), RS256 via the issuer's JWKS by kid, exact iss, exp, azp == client_id in Groundfloor mode (External: azp/cid/appid or aud), no app aud yet; roles in realm_access.roles (malformed = no roles = 403); with Multi-tenant also filter by organization. CORS for the Shell origin. Every app on the Shell site can use the user's token against any of the workspace's backends until per-app tokens ship. Off-the-shelf images: port 8080, PostgreSQL only, ephemeral disk, sessions, min instances.",
+    embedded: SERVICE_ACCESS_GUIDE,
+    lastUpdated: "2026-10-14"
+  },
   {
     id: "authentication",
     title: "Workspace Authentication",
@@ -1545,7 +1681,7 @@ var DOC_CATALOG = [
     path: "/docs/apps/shell",
     summary: "Product Apps vs Coderunner. Always gf apps init --slug <portal-slug>, then npm run release and gf apps publish --path release.zip. Never zip dist/ or upload only remoteEntry.js.",
     embedded: SHELL_APP_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "design-standard",
@@ -2356,7 +2492,7 @@ server.tool(
   "How-to for Coderunner, Shell, design-standard, css-and-styling, databases, access, m2m, authentication (app end users). Pass id from docs_list. Prefer id coderunner or coderunner-runtime before deploying. For site grants use id access. For Coderunner Vault/Files use id m2m.",
   {
     id: z.string().min(1).describe(
-      "Catalog id, e.g. coderunner | coderunner-runtime | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
+      "Catalog id, e.g. coderunner | coderunner-runtime | service-access | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
     ),
     offset: z.number().int().min(0).optional().describe(
       "Live (non-embedded) pages only: character offset to resume from. Pass nextOffset from the previous result when truncated is true."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {