@anchrd/intel 0.59.0

package/dist/http/http.types.d.ts

@@ -0,0 +1,22 @@
+import type { GateClient } from "@anchrd/gate-sdk";
+import type { AuditService } from "../audit/audit.types.js";
+import type { BrowserAuth } from "../auth/auth.types.js";
+import type { BoardService } from "../boards/boards.types.js";
+import type { BundleService } from "../bundle/bundle.types.js";
+import type { FeedService } from "../feed/feed.types.js";
+import type { FlowService } from "../flows/flows.types.js";
+import type { NodeService } from "../nodes/nodes.types.js";
+import type { ToolService } from "../tools/tools.types.js";
+export interface HttpDeps {
+    gate: Pick<GateClient, "authorize">;
+    nodes: NodeService;
+    flows: FlowService;
+    tools: ToolService;
+    bundle: BundleService;
+    audit: AuditService;
+    feed: FeedService;
+    boards: BoardService;
+    resource: string;
+    resourceMetadataUrl: string;
+    auth?: Pick<BrowserAuth, "resolve">;
+}

package/dist/http/http.types.js

@@ -0,0 +1 @@
+export {};

package/dist/indexing/indexing.d.ts

@@ -0,0 +1,6 @@
+import type { IndexingDeps } from "./indexing.types.js";
+export declare class PermanentIndexingError extends Error {
+}
+export declare function createIndexing(deps: IndexingDeps): {
+    index(versionId: string): Promise<void>;
+};

package/dist/indexing/indexing.js

@@ -0,0 +1,239 @@
+import { MaxIndexedAttachmentBytes } from "../contract/node.js";
+import { documentText } from "../shared/document-text/document-text.js";
+export class PermanentIndexingError extends Error {
+}
+// The key under which a node with exactly one vector is filed — since #390 that is every kind. It
+// is the bare node id in the index itself, which is why nothing written before anchrd/intel#301 has
+// to be renamed or embedded again.
+const wholeNodeChunkKey = "";
+// What the pass hands to `purgeVectors` at its end: the names it has just written, in case the node
+// was archived while it worked and the record of them was refused (anchrd/intel#348).
+const writtenKeys = (chunks) => chunks.map((chunk) => chunk.key);
+function indexText(mediaType, content) {
+    const text = documentText(mediaType, content);
+    // Immutable content never becomes parsable on a retry, so treating this as transient would
+    // requeue the version until the queue gives up and would bury the real cause. `documentText`
+    // answers `null` rather than throwing, because the other caller — `prompts/get` — owes its reader
+    // a different sentence about the same broken payload (#775).
+    if (text === null) {
+        throw new PermanentIndexingError("Node version content is not a valid BlockNote document");
+    }
+    return text;
+}
+/**
+ * What one chunk is embedded as (anchrd/intel#301).
+ *
+ * The node's title in front of a whole-node chunk, which is the exact string the semantic adapter
+ * used to compose on its own side. It moved here because the fingerprint has to cover what is
+ * embedded and nothing else: a prefix added downstream would sit outside the comparison and change
+ * nothing when it changed. The vector it produces therefore keeps the same name AND the same
+ * content it had before this — an upgrading installation loses no answer, though its first pass
+ * over any node does embed once more, because `node_vectors` starts empty and has no fingerprint to
+ * compare against. That cost is one embedding per node, paid when that node is next saved or when
+ * an administrator runs `reindex`, and never per card.
+ *
+ * ⚠️ Only the WHOLE-node chunk is prefixed, and the distinction is what kept a rename cheap while
+ * a node could hold many chunks: a per-chunk prefix would have put the node's title into every
+ * fingerprint, so renaming it once cost one embedding per chunk.
+ *
+ * ⚠️ The description travels with the title, for the same reason and at the same place (#816). It
+ * is a sentence about the whole node, so a per-chunk prefix would have cost one embedding per chunk
+ * for every edit of that one sentence. It is NOT put into `chunk.text`: that field is the passage a
+ * searcher is shown, and leading every citation with the description would change what the reader
+ * reads rather than what the index can match.
+ *
+ * ⚠️ An absent description leaves this string byte-identical to what it produced before #816, so an
+ * upgrading installation re-embeds only the nodes that actually carry one. A node that has a
+ * description pays exactly one embedding, on its next save or on the next `reindex`.
+ */
+function embeddedText(target, chunk) {
+    if (chunk.key !== wholeNodeChunkKey)
+        return chunk.text;
+    const description = target.description?.trim() ?? "";
+    const prefix = description === "" ? target.title : `${target.title}\n\n${description}`;
+    return `${prefix}\n\n${chunk.text}`;
+}
+/**
+ * The vectors this node needs, minus the ones it already has (anchrd/intel#301).
+ *
+ * ⚠️ This is the answer to "an unchanged chunk must not be embedded again". A save writes the
+ * whole document, so without this every save would re-embed everything it holds. The fingerprint of
+ * the exact text that was embedded is what tells an untouched chunk from a changed one.
+ *
+ * ⚠️ The comparison is against D1 and deliberately not against Vectorize. Vectorize writes are
+ * asynchronous — a vector upserted a moment ago is not readable yet — so a check made there would
+ * answer about the save before last and re-embed a node that had just been saved twice.
+ *
+ * ⚠️ The record is written only after the upsert returned, in the caller. A pass that dies in
+ * between leaves the record short, so the next one embeds again; the opposite order would leave a
+ * record claiming a vector nobody ever wrote, and nothing would ever notice.
+ */
+async function replaceVectors(deps, target, chunks) {
+    const semantic = deps.semantic;
+    if (!semantic)
+        return;
+    const stored = await deps.repository.listVectors(target.nodeId);
+    const known = new Map(stored.map((record) => [record.chunkKey, record.fingerprint]));
+    const records = [];
+    const changed = [];
+    for (const chunk of chunks) {
+        const text = embeddedText(target, chunk);
+        const fingerprint = await deps.hash(text);
+        if (known.get(chunk.key) !== fingerprint)
+            changed.push({ key: chunk.key, text });
+        records.push({ chunkKey: chunk.key, fingerprint, passage: chunk.text });
+    }
+    const wanted = new Set(chunks.map((chunk) => chunk.key));
+    const stale = stored.map((record) => record.chunkKey).filter((key) => !wanted.has(key));
+    // ⚠️ The one-time sweep of the vector this node had BEFORE it was chunked. An empty record with a
+    // chunked node means this is the first pass since anchrd/intel#301 (or since `reindex` emptied
+    // the record), and the whole-node vector written under the bare node id is still sitting there —
+    // matching questions and answering with the wrong card's passage. Once a record exists this
+    // branch is never taken again, so it costs one call per node rather than one per save.
+    if (stored.length === 0 && !wanted.has(wholeNodeChunkKey))
+        stale.push(wholeNodeChunkKey);
+    await semantic.upsert(target, changed);
+    if (stale.length > 0)
+        await semantic.remove(target.nodeId, stale);
+    await deps.repository.replaceVectors(target, records);
+}
+/**
+ * Everything an archived node had in the vector index, taken out of it (anchrd/intel#348).
+ *
+ * ⚠️ The ORDER is the whole safety argument, and it is the exact mirror of the one above. There the
+ * record is written last, because a row claiming a vector nobody wrote would make the next pass skip
+ * that card forever. Here the record is DELETED last, because the row is the only thing that knows
+ * what a vector is called: drop it first and the vectors stay in the index under names nothing left
+ * anywhere can produce. A pass that dies in between leaves vectors already gone and a record that
+ * still names them — which costs the next pass one embedding per card and nothing else, because the
+ * queue redelivers this message and the second run asks Vectorize to forget names it has already
+ * forgotten. Both failures are repaired by repeating; neither ends in a wrong answer.
+ *
+ * ⚠️ The bare node id goes with them whether or not it is in the record. That name is the ONE vector
+ * a node can hold without any record of it — everything written before anchrd/intel#301 is filed
+ * under it — and an archived node has no later pass in which the one-time sweep in `replaceVectors`
+ * could find it. The standing cost of that is one `deleteByIds` of a single name on a redelivered
+ * message, which Vectorize answers without complaint for an id it no longer holds.
+ *
+ * ⚠️ `alsoNamed` is what makes this run after a NORMAL pass too, and it closes the one hole a purge
+ * driven from `archive` alone cannot. A pass that has already upserted its vectors when somebody
+ * archives the node writes no record at all — `replaceVectors` refuses on `archived_at IS NULL` —
+ * so those vectors would sit in the index with nothing anywhere able to name them, and no message
+ * left to repair it. The pass knows the names it just wrote, so it hands them over.
+ *
+ * ⚠️ Without a semantic index configured nothing happens at all, `node_vectors` included. The rows
+ * can only have been written while one WAS configured, so a deployment that has temporarily lost the
+ * binding must not take the record away — that would leave the vectors behind it unnameable, which
+ * is the failure this whole function exists to avoid.
+ *
+ * ⚠️ One race is left and it is the harmless direction: a restore that lands between the read below
+ * and the deletion loses the vectors that restore's own pass had just written. The node keeps
+ * answering out of the lexical half — `hydrateVisibleCitations` falls back on the full-text passage
+ * when there is no `node_vectors` row — and the next save or `reindex` puts the vectors back. The
+ * record is gone with them, so nothing claims otherwise in the meantime.
+ */
+async function purgeVectors(deps, versionId, alsoNamed = []) {
+    const semantic = deps.semantic;
+    if (!semantic)
+        return;
+    const nodeId = await deps.repository.archivedNodeId(versionId);
+    if (nodeId === null)
+        return;
+    const recorded = (await deps.repository.listVectors(nodeId)).map((record) => record.chunkKey);
+    const keys = [...new Set([wholeNodeChunkKey, ...recorded, ...alsoNamed])];
+    await semantic.remove(nodeId, keys);
+    await deps.repository.deleteVectors(nodeId);
+}
+/**
+ * Whether this version's bytes are read at all (#821).
+ *
+ * ⚠️ The question is asked from the SIZE, before anything is fetched, and that is the point: a
+ * 50 MB attachment read into memory and handed to the converter as a blob beside it is the whole
+ * budget of the isolate, and the pass would end at a limit rather than in an answer. The file is
+ * stored either way; what it loses is a search over its text, and it keeps one over its name
+ * because the title is its own column in `node_fts` and weighted above the content.
+ *
+ * ⚠️ Attachments only. Every other kind is text this Worker wrote itself, and the one whose size
+ * this field cannot describe — a table, whose content is spread over its versions — is not an
+ * attachment.
+ */
+function tooLargeToRead(target) {
+    return target.kind === "attachment" && target.size > MaxIndexedAttachmentBytes;
+}
+async function readCanonical(deps, target) {
+    if (target.kind === "attachment") {
+        const key = target.contentKeys[0];
+        return key === undefined ? null : await deps.content.getBytes(key);
+    }
+    const segments = await Promise.all(target.contentKeys.map(async (key) => await deps.content.get(key)));
+    if (segments.length === 0 || segments.some((segment) => segment === null))
+        return null;
+    return segments.join("");
+}
+export function createIndexing(deps) {
+    return {
+        async index(versionId) {
+            const target = await deps.repository.getTarget(versionId);
+            // ⚠️ No target has meant "nothing to do" since the pass existed, and for a superseded version
+            // it still does. For an ARCHIVED node it never did: its vectors stayed in the index, invisible
+            // because every citation is hydrated through a join on `nodes` — and costing places in a
+            // candidate list that Vectorize caps at 100 for everybody (anchrd/intel#348). `purgeVectors`
+            // is the one that tells the two apart; this call cannot.
+            if (!target) {
+                await purgeVectors(deps, versionId);
+                return;
+            }
+            // A file too big to hold: indexed under its name, with no text beside it, and NOT read
+            // (#821). It ends as a finished pass rather than an error, because nothing here is broken and
+            // a retry would fail in exactly the same way, forever.
+            if (tooLargeToRead(target)) {
+                const chunks = [{ key: wholeNodeChunkKey, title: target.title, text: "" }];
+                await deps.repository.replace(target, chunks);
+                await replaceVectors(deps, target, chunks);
+                await purgeVectors(deps, versionId, writtenKeys(chunks));
+                await deps.repository.markIndexed(versionId, deps.now().toISOString());
+                return;
+            }
+            // An attachment is one object of bytes; text kinds may be several, because a table's content
+            // is the join of its versions (#40). A missing segment fails the whole pass rather than
+            // indexing a table with a hole in it.
+            const canonical = await readCanonical(deps, target);
+            if (canonical === null) {
+                await deps.repository.markError(versionId, "content_missing", deps.now().toISOString());
+                throw new Error("Node version content is missing");
+            }
+            try {
+                const text = typeof canonical === "string"
+                    ? indexText(target.mediaType, canonical)
+                    : target.mediaType.startsWith("text/")
+                        ? new TextDecoder().decode(canonical)
+                        : await deps.converter?.convert(target.title, target.mediaType, canonical);
+                if (text === undefined) {
+                    throw new PermanentIndexingError(`No document converter is configured for ${target.mediaType}`);
+                }
+                // ⚠️ One chunk per node since #390, and the LIST is what stays. Both indexes read it, so
+                // they cannot come to disagree about what a node is made of — which is the property that
+                // let a board be one passage and one vector per card (#285, anchrd/intel#301) without
+                // either half being told about it separately.
+                const chunks = [{ key: wholeNodeChunkKey, title: target.title, text }];
+                await deps.repository.replace(target, chunks);
+                await replaceVectors(deps, target, chunks);
+                // ⚠️ Asked again, at the END of a pass that started on a live node (anchrd/intel#348). The
+                // node may have been archived while this pass was embedding, and then `replaceVectors` above
+                // wrote no record at all — its statements refuse on `archived_at IS NULL`. The vectors are in
+                // the index either way, so without this they would stay there with nothing anywhere able to
+                // name them and no message left to try again: the archive's own pass has an empty record to
+                // read from. One extra `SELECT` per pass buys that, and on a live node it answers null.
+                await purgeVectors(deps, versionId, writtenKeys(chunks));
+                await deps.repository.markIndexed(versionId, deps.now().toISOString());
+            }
+            catch (error) {
+                // Only Intel's own permanent messages are stored. A converter or fetch failure can carry
+                // content excerpts or URLs with query parameters, and this column is read by operators and
+                // shown in the UI, so an arbitrary upstream message must not be persisted here.
+                await deps.repository.markError(versionId, error instanceof PermanentIndexingError ? error.message.slice(0, 500) : "indexing_failed", deps.now().toISOString());
+                throw error;
+            }
+        },
+    };
+}

package/dist/indexing/indexing.types.d.ts

@@ -0,0 +1,11 @@
+import type { DocumentConverter } from "../adapters/document-converter/document-converter.types.js";
+import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+import type { ContentStore, NodeIndexRepository } from "../nodes/nodes.types.js";
+export interface IndexingDeps {
+    repository: NodeIndexRepository;
+    content: ContentStore;
+    semantic?: SemanticIndex | undefined;
+    converter?: DocumentConverter | undefined;
+    hash(content: string): Promise<string>;
+    now(): Date;
+}

package/dist/indexing/indexing.types.js

@@ -0,0 +1 @@
+export {};

package/dist/intel/intel.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+import type { IntelDeps } from "./intel.types.js";
+export declare function createIntel(deps: IntelDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/intel/intel.js

@@ -0,0 +1,194 @@
+import { Hono } from "hono";
+import { createHttp } from "../http/http.js";
+import { handleMcp } from "../mcp/mcp.js";
+import { authorize, authorizeBearer, bearer, } from "../shared/gate-authorization/gate-authorization.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { intelProblem, problemDetails } from "../shared/problem-details/problem-details.js";
+import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
+export function createIntel(deps) {
+    const baseUrl = deps.baseUrl.replace(/\/+$/, "");
+    const resource = `${baseUrl}/mcp`;
+    // RFC 9728 inserts the well-known segment between host and resource path: the document for a
+    // resource ending in /mcp belongs at /.well-known/oauth-protected-resource/mcp. A client that
+    // constructs that URL itself — Intel's own portal client in adapters/openid is one — finds
+    // nothing under the bare root path, and only a client that follows WWW-Authenticate gets through.
+    const resourceMetadataUrl = `${baseUrl}/.well-known/oauth-protected-resource/mcp`;
+    const app = new Hono();
+    app.onError((error, context) => {
+        if (error instanceof IntelError) {
+            return context.json(intelProblem(error), error.status);
+        }
+        // An IntelError is an expected refusal and explains itself; the unknown exception must leave a
+        // trace, or the 500 is undiagnosable — the worker answered, so the platform records no
+        // exception of its own (#93). The body stays generic: the log is the operator's channel.
+        reportUnexpectedError(error);
+        return context.json(problemDetails(500, "internal_error", "Internal server error"), 500);
+    });
+    app.get("/health", (context) => context.json({ status: "ok" }));
+    const resourceMetadata = {
+        resource,
+        authorization_servers: [deps.gateUrl.replace(/\/+$/, "")],
+        bearer_methods_supported: ["header"],
+    };
+    app.get("/.well-known/oauth-protected-resource/mcp", (context) => context.json(resourceMetadata));
+    // The root path stays as a compatibility alias: 0.2.0 published the document only here, and a
+    // client that stored that URL from an earlier WWW-Authenticate header keeps working.
+    app.get("/.well-known/oauth-protected-resource", (context) => context.json(resourceMetadata));
+    const browserAuth = deps.auth;
+    if (browserAuth) {
+        app.get("/auth/login", async (context) => await browserAuth.login(new URL(context.req.url)));
+        // One connect route for the one portal: there are no per-source connections any more. With
+        // `?silent=1` it runs `prompt=none`, which is how the Tools screen reaches it without anybody
+        // clicking (#60); the route itself is unchanged otherwise, including who may use it.
+        app.get("/auth/connect", async (context) => {
+            const connectReturnTo = encodeURIComponent("/auth/connect?returnTo=/tools");
+            const session = await browserAuth.resolve(context.req.raw.headers);
+            if (!session) {
+                return context.redirect(`/auth/login?returnTo=${connectReturnTo}`);
+            }
+            const authorization = await authorizeBearer(deps.gate, session.bearer, resource);
+            if (!authorization) {
+                return context.redirect(`/auth/login?returnTo=${connectReturnTo}`);
+            }
+            // ⚠️ 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 {
+                return await browserAuth.connect(new URL(context.req.url), context.req.raw.headers, authorization.identity.id);
+            }
+            catch (error) {
+                if (error instanceof IntelError) {
+                    return context.redirect(`/tools?connectError=${encodeURIComponent(error.code)}`);
+                }
+                // ⚠️ Everything else used to be rethrown, and the outer handler turned it into a bare 500
+                // with a generic body (#425). For an API that is the right answer; for a route a BROWSER is
+                // sent to it is a dead end — the reader gets JSON instead of a screen, and the Tools page
+                // never learns that the attempt happened at all, so it says "no access" about a sign-in
+                // that crashed.
+                //
+                // The trace still goes to the log, which is the operator's channel; what changes is that
+                // the reader is returned to a screen that can say "this broke" instead of "you may not".
+                reportUnexpectedError(error);
+                return context.redirect("/tools?connectError=portal_sign_in_failed");
+            }
+        });
+        // The other end of the same walk: `/auth/connect` starts it, `/auth/callback` finishes it, and
+        // a reader who lands in a white JSON page does not distinguish which of the two put them there
+        // (#444). Everything that reaches this catch has already lost its handoff — `callback` answers
+        // the paths that still know where the person wanted to go — so the destination here is a
+        // DECIDED one rather than a remembered one.
+        //
+        // ⚠️ `/tools` and not `/`: it is the only screen that reads `connectError` and turns it into a
+        // sentence (`portalAnswerOf`), and every code but the two about access lands on "the sign-in is
+        // broken" there — which is what happened. The root would take the reader somewhere that says
+        // nothing at all about the attempt they just made. Somebody who has no Intel session either is
+        // sent on to the login by the interface's own 401 handling, once, bounded by the sign-in loop
+        // guard (#118).
+        app.get("/auth/callback", async (context) => {
+            try {
+                return await browserAuth.callback(new URL(context.req.url), context.req.raw.headers);
+            }
+            catch (error) {
+                // ⚠️ The IntelError is logged here although `app.onError` deliberately does not log one:
+                // an expected refusal explains itself through its body, and this route no longer has a
+                // body. `oauth_session_invalid` is raised for two different situations — no readable
+                // handoff at all, and a Gate login handoff that ran out — and a deployment where EVERY
+                // callback fails (a rotated session key, a clock that drifted, a cookie the browser stopped
+                // sending) looks from the outside exactly like one person with a stale tab. Without this
+                // line nothing anywhere tells the two apart.
+                reportUnexpectedError(error);
+                const code = error instanceof IntelError ? error.code : "portal_sign_in_failed";
+                return context.redirect(`/tools?connectError=${encodeURIComponent(code)}`);
+            }
+        });
+        app.post("/auth/logout", () => browserAuth.logout());
+    }
+    app.route("/api/v1", createHttp({
+        gate: deps.gate,
+        nodes: deps.nodes,
+        flows: deps.flows,
+        tools: deps.tools,
+        bundle: deps.bundle,
+        audit: deps.audit,
+        feed: deps.feed,
+        boards: deps.boards,
+        resource,
+        resourceMetadataUrl,
+        ...(deps.auth ? { auth: deps.auth } : {}),
+    }));
+    app.all("/mcp", async (context) => {
+        const authorization = await authorize(deps.gate, context.req.raw.headers, resource);
+        if (!authorization) {
+            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
+            // it as the caller and not as Intel. There is no cookie path on `/mcp`, so `bearer` is the
+            // same value `authorize` just used — read again rather than passed out of it, because a
+            // function that returned a credential beside its answer would be one somebody logs.
+            bearer: bearer(context.req.raw.headers) ?? "",
+            flows: deps.flows,
+            nodes: deps.nodes,
+            tools: deps.tools,
+            bundle: deps.bundle,
+            audit: deps.audit,
+            feed: deps.feed,
+            boards: deps.boards,
+            prompts: deps.prompts,
+        });
+    });
+    return app;
+}

package/dist/intel/intel.types.d.ts

@@ -0,0 +1,24 @@
+import type { GateClient } from "@anchrd/gate-sdk";
+import type { AuditService } from "../audit/audit.types.js";
+import type { BrowserAuth } from "../auth/auth.types.js";
+import type { BoardService } from "../boards/boards.types.js";
+import type { BundleService } from "../bundle/bundle.types.js";
+import type { FeedService } from "../feed/feed.types.js";
+import type { FlowService } from "../flows/flows.types.js";
+import type { NodeService } from "../nodes/nodes.types.js";
+import type { Prompts } from "../prompts/prompts.types.js";
+import type { ToolService } from "../tools/tools.types.js";
+export interface IntelDeps {
+    baseUrl: string;
+    gateUrl: string;
+    gate: Pick<GateClient, "authorize">;
+    nodes: NodeService;
+    flows: FlowService;
+    tools: ToolService;
+    bundle: BundleService;
+    audit: AuditService;
+    feed: FeedService;
+    boards: BoardService;
+    prompts: Prompts;
+    auth?: BrowserAuth;
+}

package/dist/intel/intel.types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { McpDeps } from "./mcp.types.js";
+export declare function handleMcp(request: Request, deps: McpDeps): Promise<Response>;