@anchrd/intel-api 0.17.0 → 0.19.0

package/README.md

@@ -263,6 +263,21 @@ grants them.
 
 A missing capability answers **`403`**, and the screen says a permission is missing.
 
+⚠️ **`mcp.connect` is the one that gates a whole endpoint rather than an action.** Intel's own MCP
+endpoint (`POST /mcp`, the one an MCP client or a portal connects to) checks it **on every request**
+and answers `403` without it — before any tool runs and before anything is read. Two things follow
+for an operator:
+
+- **Somebody who should use Intel through an MCP client needs `mcp.connect` in Intel**, beside their
+  `nodes.*` capabilities. Without it the client authenticates successfully and every call is refused.
+- **Revoking it takes effect on the next call**, with no new sign-in and nothing to press. If a
+  Cloudflare Access policy in front of the endpoint also compares the `mcp` claim, that layer is the
+  slower of the two — the claim is written once per sign-in and a running session carries it for up
+  to 24 hours, while this check reads the live grant rows every time.
+
+The web UI is unaffected: it speaks the HTTP surface, which is gated by `nodes.*`, `flows.*` and
+`tools.*` as before.
+
 ### Layer two: the grant on the node
 
 What somebody may reach *in this tree*, granted in Intel on a node. Four verbs — `read`, `write`,
@@ -348,10 +363,24 @@ both, every silent sign-in is refused and the Tools area shows "No access to the
 correct behaviour for somebody outside every policy, and a misleading one for a deployment that
 simply never enabled the setting.
 
-⚠️ **Today, somebody without the Gate `mcp.connect` capability is sent into that sign-in anyway**
-and can land on the portal's own error page, outside Intel, with no way back but the browser's back
-button. Grant `mcp.connect` alongside the Intel capabilities to everyone who should reach Tools.
-Tracked as anchrd/intel#434.
+⚠️ **Somebody who carries the Gate capability `mcp.connect` at no service at all is not sent into
+that sign-in.** Gate answers that question service-wide, Intel asks it before the first redirect,
+and the person stays here reading a sentence that says whom to ask — rather than landing on the
+portal's own error page, outside Intel, with no way back but the browser's back button
+(anchrd/intel#434). Grant `mcp.connect` alongside the Intel capabilities to everyone who should
+reach Tools.
+
+Two things that guard deliberately does not do. It **names no server**: the answer is one bit, so
+somebody who may reach a different product's MCP server walks on and sees what the portal offers
+them. And it **promises nothing** — this is the part worth knowing before you grant: the portal
+decides on the `mcp` claim frozen into the ID token, and a running Cloudflare Access session carries
+the old claim for up to 24 hours. ⚠️ **Inside that window the old dead end is still open.** Somebody
+who was granted `mcp.connect` a minute ago is not refused here, walks on, and Access then decides on
+the claim state that produced the error page in the first place. The guard closes the trip that is
+certainly pointless; it does not close this one. The way out is the same as before — sign out of
+Access and in again, so a new ID token carries the new claim. (Not measured against a running
+installation; the claim lifetime is the documented one.) Against a Gate too old to answer the
+question at all, nobody is refused here.
 
 The Tools screen distinguishes four situations rather than calling all of them "no access": a
 refusal that really came back, an expired connection, a sign-in that broke, and a sign-in that was

package/dist/intel/intel.js

@@ -50,7 +50,32 @@ export function createIntel(deps) {
             if (!authorization) {
                 return context.redirect(`/auth/login?returnTo=${connectReturnTo}`);
             }
-            if (!authorization.can("tools", "read")) {
+            // ⚠️ Two questions, and both are answered BEFORE the first redirect leaves Intel (#434).
+            // `tools:read` is Intel's own door. `mcpPortalRefused()` is Gate's answer to a question Intel
+            // cannot ask itself: does this person carry `mcp.connect` at ANY service? Measured against the
+            // running installation, somebody without it was sent to `mcp.anchrd.sh/servers-callback` and
+            // landed on a white page saying "No allowed servers available, check your Zero trust policies"
+            // — a sentence written for an administrator, on a foreign domain, with not one clickable
+            // element on it.
+            //
+            // ⚠️ The helper, never the raw `mcpConnectAnywhere` beside it. The field has THREE states, and
+            // `undefined` means "this Gate is older than the question" (anchrd/gate#277), not "nowhere".
+            // `if (!authorization.mcpConnectAnywhere)` passes `tsc --noEmit` and `biome check` alike and
+            // would turn every reader of such an installation away without a word — the difference is a
+            // value, not a type, so nothing but this line prevents it (anchrd/gate#288).
+            //
+            // ⚠️ And it is deliberately NOT `can("mcp", "connect")`, which is what this guard was first
+            // built as: Gate trims `rules` to the ASKING service (GATE-64, least privilege), so that asks
+            // `intel.mcp.connect`. The portal is a door onto every server — somebody carrying
+            // `dwh.mcp.connect` reaches it and sees the dwh tools, and that spelling would have locked
+            // them out. The bit knows no service names, on purpose; it is one bit and carries no more.
+            //
+            // ⚠️ It spares the certainly wasted trip and promises no successful one: the portal decides
+            // on the `mcp` claim frozen into the ID token, and a running Access session carries the old
+            // claim for up to 24 hours. Somebody granted a minute ago is NOT refused here, walks on, and
+            // meets Access deciding on the very claim state this ticket is about — inside that window the
+            // old dead end is still open, and this guard does not close it. It closes the certain one.
+            if (!authorization.can("tools", "read") || authorization.mcpPortalRefused()) {
                 return context.redirect("/tools?connectError=permission_required");
             }
             try {
@@ -91,6 +116,32 @@ export function createIntel(deps) {
             context.header("WWW-Authenticate", `Bearer resource_metadata="${resourceMetadataUrl}"`);
             return context.json({ jsonrpc: "2.0", id: null, error: { code: -32003, message: "authentication required" } }, 401);
         }
+        // ⚠️ Intel's OWN portal door, asked per request — and it is deliberately the service-trimmed
+        // `can`, the exact spelling the guard on `/auth/connect` above must never use (anchrd/gate#293).
+        // The two questions are different and both are needed:
+        //
+        //   /auth/connect  "is anything in the SHARED portal for this person"   mcpPortalRefused()
+        //   /mcp           "may they reach THIS server"                         can("mcp", "connect")
+        //
+        // Until now only Cloudflare Access asked the second one, comparing the `mcp` claim of the Access
+        // application against the service name. That claim is collected when the person signs in and a
+        // running Access session carries it for up to 24 hours, so a revoked grant kept working for a
+        // day while `rules` — the same rows, read live on every call — already said no. This line moves
+        // the decision to where the answer is: a revocation lands on the NEXT call, with no new sign-in,
+        // no session revocation and nobody pressing anything. It also lets the Access policy go coarse
+        // ("is a Gate user") without opening the server to everyone.
+        //
+        // ⚠️ NOT `permits(...)`: `intel.admin` is the bootstrap escape for Intel's own resource ACLs
+        // (ADR-0004 §6), and there is no bootstrap here — this grant is set in Gate, not in Intel, so no
+        // admin has to be able to hand it to themselves through this door. Widening it would let people
+        // in whom the Access policy turns away today, which is the opposite of moving a check.
+        //
+        // ⚠️ Fails CLOSED, and that is the whole reason a `403` and not a `401`: the caller IS
+        // authenticated and merely may not, so a `WWW-Authenticate` challenge would send an MCP client
+        // round the OAuth loop it just completed — the certain dead end of #434 in another costume.
+        if (!authorization.can("mcp", "connect")) {
+            return context.json({ jsonrpc: "2.0", id: null, error: { code: -32003, message: "permission required" } }, 403);
+        }
         return await handleMcp(context.req.raw, {
             authorization,
             // ⚠️ The very token this call was authorized with, so a tool that has to speak to Gate does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,7 +42,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.7.0",
+    "@anchrd/gate-sdk": "^0.15.0",
     "@anchrd/intel-contract": "^0.15.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",