@anchrd/intel-api 0.18.0 → 0.20.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`,

package/dist/adapters/cloudflare/cloudflare.js

@@ -117,6 +117,9 @@ export default {
             semantic,
             externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
             flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
+            // ⚠️ The real one, like its two neighbours: the refusal is only worth anything if it reads
+            // real published graphs and the real visibility predicate (#457).
+            flowsUsingNode: async (who, nodeId) => await flowRepository.flowsUsingNode({ ...who, canRun: true }, nodeId),
             // ⚠️ `canExecute: true` is not a permission being granted here — the servers list touches
             // nothing and executes nothing. It exists because `ToolActor` carries the flag for the one
             // method that needs it, and a `false` would read as if listing were gated on execution.

package/dist/adapters/db/db-flows.js

@@ -275,6 +275,120 @@ export function createFlowRepository(deps) {
                 hidden: rows.filter((row) => row.visible !== 1).length,
             };
         },
+        // Who calls THIS flow — the sibling of `externalCallers`, which asks the same question about a
+        // whole folder (#457). Same shape: what the actor may see by name, the rest as a number, because
+        // a refusal must not become a way of learning that a flow one cannot see exists.
+        async flowCallers(actor, flowId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          JOIN json_each(version.graph_json, '$.nodes') node
+          WHERE json_extract(node.value, '$.kind') = 'subflow'
+            AND json_extract(node.value, '$.configuration.flowId') = ?
+            AND flow.archived_at IS NULL
+            AND flow.id <> ?
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), flowId, flowId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // Published flows whose graph reads THIS node as a step (#457) — the mirror of `nodeReferences`,
+        // which asks the same graph the other way round ("which documents do the flows in this folder
+        // read"). Same visible/hidden shape as every other refusal: a title only where the actor may see
+        // it, the rest counted, so a refusal never becomes a directory of the tree (ADR-0004 §3).
+        async flowsUsingNode(actor, nodeId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          JOIN json_each(version.graph_json, '$.nodes') node
+          WHERE json_extract(node.value, '$.kind') IN (${treeLinkKindList})
+            AND json_extract(node.value, '$.configuration.resourceId') = ?
+            AND flow.archived_at IS NULL
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), nodeId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // ⚠️ BOTH directions, and the second one was missing (found in review). A run of this flow can be
+        // the PARENT of somebody else's run — deleting it takes the record of what started theirs. It can
+        // just as well be the CHILD of somebody else's run, and deleting that leaves the caller standing
+        // on a sub-flow node whose callee is gone: it can never be completed, and migration 0010's stall
+        // rule then sweeps the caller to `failed`. A history with a hole is not a history, in either
+        // direction.
+        async hasEntangledRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found
+          FROM flow_runs mine
+          JOIN flow_runs other
+            ON other.parent_run_id = mine.id OR other.id = mine.parent_run_id
+          WHERE mine.flow_id = ? AND other.flow_id <> ?
+          LIMIT 1`)
+                .bind(flowId, flowId)
+                .first();
+            return row !== null;
+        },
+        // ⚠️ Archiving deliberately leaves runs in flight alone — restoring the flow is what makes them
+        // readable again (`flows.ts`). A purge takes that way back with it, so a run that has not
+        // finished refuses the deletion rather than being deleted mid-execution.
+        async hasUnfinishedRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM flow_runs
+          WHERE flow_id = ? AND status IN ('queued', 'running', 'waiting') LIMIT 1`)
+                .bind(flowId)
+                .first();
+            return row !== null;
+        },
+        async purgeFlow(input) {
+            const aliveFlow = "EXISTS (SELECT 1 FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL)";
+            const deleted = await deps.db.batch([
+                // ⚠️ FIRST, reading the title out of the row that falls at the end of this batch. Afterwards
+                // nothing can look a name up, and an entry carrying only an id names something nobody can
+                // find again (`anchrd/gate#146`).
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'flows.purge', 'flow', f.id, json_object('title', f.title), ?
+            FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL`)
+                    .bind(input.auditId, input.actorId, input.occurredAt, input.flowId),
+                // The runs are this flow's history: the steps hang off the runs, the runs off the flow.
+                // ⚠️ The guard belongs on EVERY statement, not only the last: a batch whose final statement
+                // matches nothing still COMMITS, so a restore in between would empty a living flow's history
+                // and answer `409` as if nothing had happened.
+                deps.db
+                    .prepare(`DELETE FROM flow_run_steps
+            WHERE run_id IN (SELECT id FROM flow_runs WHERE flow_id = ?) AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_runs WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_versions WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                // ⚠️ LAST, and still guarded — a restore between the service's check and this statement
+                // would otherwise cost a living flow.
+                deps.db
+                    .prepare("DELETE FROM flows WHERE id = ? AND archived_at IS NOT NULL")
+                    .bind(input.flowId),
+            ]);
+            return (deleted.at(-1)?.meta?.changes ?? 0) === 0 ? "missing" : { purged: true };
+        },
         // The documents the flows in this folder's subtree read, so whoever shares the folder
         // can be told what the grant does not cover (ADR-0004 §4).
         //

package/dist/adapters/db/db.js

@@ -620,6 +620,106 @@ export function createNodeRepository(deps) {
                 .first();
             return row ? mapNode(row) : "conflict";
         },
+        async hasAnyChild(nodeId) {
+            // ⚠️ Without a visibility predicate and without an archived filter, both on purpose: this
+            // answers whether the row can be deleted at all, not what somebody may look at (#457).
+            //
+            // ⚠️ BOTH tables, and that is not defensive breadth: knowledge and flows share ONE tree
+            // (ADR-0004), `flows.parent_id` references `nodes(id)` since migration 0002, and a folder whose
+            // only content is a flow answered "empty" while it was not. Purging it left the flow with a
+            // parent that no longer exists — invisible in the tree, unreachable, unmovable.
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM nodes WHERE parent_id = ?
+          UNION ALL
+          SELECT 1 AS found FROM flows WHERE parent_id = ?
+          LIMIT 1`)
+                .bind(nodeId, nodeId)
+                .first();
+            return row !== null;
+        },
+        // The names this node's vectors carry in the external index. They are read BEFORE the row falls,
+        // because `node_vectors` is the only thing that knows them — and once it is gone, an orphan in
+        // Vectorize can never be named again (#457).
+        async listVectorKeys(nodeId) {
+            const rows = await deps.db
+                .prepare("SELECT chunk_key FROM node_vectors WHERE node_id = ?")
+                .bind(nodeId)
+                .all();
+            return (rows.results ?? []).map((row) => row.chunk_key);
+        },
+        async countInboundLinks(nodeId) {
+            const row = await deps.db
+                .prepare("SELECT COUNT(*) AS n FROM node_links WHERE target_node_id = ?")
+                .bind(nodeId)
+                .first();
+            return row?.n ?? 0;
+        },
+        async purgeNode(input) {
+            // The keys BEFORE anything falls: after the batch there is no version row left to read them
+            // from, and an object nobody can name is an object nobody can delete.
+            const keys = await deps.db
+                .prepare("SELECT content_key FROM node_versions WHERE node_id = ?")
+                .bind(input.nodeId)
+                .all();
+            // ⚠️ The guard belongs on EVERY statement, not only on the last one (found in review). A
+            // `D1.batch` is one implicit transaction, but a final statement that changes ZERO rows is not
+            // an error — the transaction commits. With the condition only at the end, a restore between
+            // the service's check and this batch deleted every version, grant, link and index row of a
+            // node that was alive again, left its row standing, and answered `409 update_conflict`: the
+            // reader was told nothing had happened while the content was already gone. The audit row
+            // carried the same condition, so it was not even booked.
+            const alive = "EXISTS (SELECT 1 FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL)";
+            const deleted = await deps.db.batch([
+                // ⚠️ FIRST, and reading the title out of the row that falls at the end of this batch. Its
+                // `WHERE EXISTS` is what makes it honest: no row, no entry — a purge that hit nothing does
+                // not book one.
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'node.purge', 'node', n.id,
+              json_patch(?, json_object('title', n.title, 'kind', n.kind)), ?
+            FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL`)
+                    .bind(input.auditId, input.actorId, JSON.stringify(input.metadata), input.occurredAt, input.nodeId),
+                // The derived indexes go with their source. ⚠️ A hit on a deleted document is not a blemish
+                // but a leak: the title stands in the result and the content is gone.
+                deps.db
+                    .prepare(`DELETE FROM node_fts WHERE node_id = ? AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`DELETE FROM node_vectors WHERE node_id = ? AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`DELETE FROM node_index_state
+            WHERE version_id IN (SELECT id FROM node_versions WHERE node_id = ?) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // Both directions. Outgoing links belong to this node; incoming ones would otherwise point
+                // at a row that is gone, and a foreign key would refuse the delete anyway.
+                deps.db
+                    .prepare(`DELETE FROM node_links
+            WHERE (source_node_id = ? OR target_node_id = ?) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId, input.nodeId),
+                // A permission on a node that does not exist is a dangling permission.
+                deps.db
+                    .prepare(`DELETE FROM node_grants WHERE node_id = ? AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`DELETE FROM node_versions WHERE node_id = ? AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // ⚠️ The replay keys of every earlier write to this node. Left behind, a later write reusing
+                // one of them would be answered with a resource id that no longer resolves.
+                deps.db
+                    .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // LAST — and its count is what the caller reads as the verdict.
+                deps.db
+                    .prepare("DELETE FROM nodes WHERE id = ? AND archived_at IS NOT NULL")
+                    .bind(input.nodeId),
+            ]);
+            const removed = deleted.at(-1)?.meta?.changes ?? 0;
+            if (removed === 0)
+                return "missing";
+            return { contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))] };
+        },
         async appendVersion(input) {
             const version = input.version;
             await deps.db.batch([

package/dist/flows/flows.js

@@ -270,6 +270,16 @@ function decodeCursor(cursor) {
         throw new IntelError(400, "flow_run_cursor_invalid", "Page cursor is invalid");
     return { createdAt, id };
 }
+// ⚠️ Named where the reader may see it, counted where they may not — the same rule the folder's
+// refusal follows (`callersDetail` in nodes.ts): a refusal must not become a way of learning that a
+// flow one cannot see exists (ADR-0004 §3).
+function callersDetail(callers) {
+    const named = callers.visible.map((title) => `“${title}”`).join(", ");
+    const rest = callers.hidden === 0
+        ? ""
+        : `${named ? " and " : ""}${callers.hidden} more flow${callers.hidden === 1 ? "" : "s"} you cannot see`;
+    return `Published flows still call this one: ${named}${rest}. Change or unpublish them first.`;
+}
 export function createFlows(deps) {
     async function requireFlow(actor, flowId) {
         const flow = await deps.repository.getVisible(actor, flowId);
@@ -1146,6 +1156,48 @@ export function createFlows(deps) {
             }
             return updated;
         },
+        /**
+         * ⚠️ The flow half of #457 — after this a flow is really gone, with its versions and the record
+         * of every run it ever had. Read the decisions on that issue before touching it.
+         */
+        async purge(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            // ⚠️ THE structural guard, same as the node's: a living flow has no path into nothing.
+            if (!current.archivedAt) {
+                throw new IntelError(409, "flow_not_archived", "Only an archived flow can be deleted for good. Archive it first.");
+            }
+            // A published caller would break at RUN TIME, in front of somebody who did not order this.
+            const callers = await deps.repository.flowCallers(actor, current.id);
+            if (callers.visible.length || callers.hidden) {
+                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers));
+            }
+            // ⚠️ The one thing a flow has that a node does not: its runs can be the PARENT of runs
+            // belonging to other flows. Deleting them would take the record of who started those runs
+            // with it — a history with a hole is not a history, so this refuses instead.
+            if (await deps.repository.hasEntangledRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_entangled", "Runs of this flow are tied to runs of other flows. Deleting them would leave those without the record of what started them, or without the run they are waiting for.");
+            }
+            // ⚠️ Archiving deliberately leaves a run in flight alone, because restoring the flow makes it
+            // readable again. A purge takes that way back with it — so an unfinished run refuses.
+            if (await deps.repository.hasUnfinishedRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_unfinished", "This flow still has runs that have not finished. Wait for them or cancel them first.");
+            }
+            const purged = await deps.repository.purgeFlow({
+                flowId: current.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+            });
+            if (purged === "missing") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return { purged: true, title: current.title };
+        },
         /**
          * Archive a flow, or take it back out again.
          *

package/dist/flows/flows.types.d.ts

@@ -88,6 +88,24 @@ export interface FlowRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Flow>;
+    flowsUsingNode(actor: FlowActor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowCallers(actor: FlowActor, flowId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    hasEntangledRuns(flowId: string): Promise<boolean>;
+    hasUnfinishedRuns(flowId: string): Promise<boolean>;
+    purgeFlow(input: {
+        flowId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<"missing" | {
+        purged: true;
+    }>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
     listVersions(flowId: string): Promise<Omit<FlowVersionSummary, "published">[]>;
     getVersions(versionIds: string[]): Promise<FlowVersion[]>;
@@ -213,6 +231,12 @@ export interface FlowService {
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
     update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
     archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;
+    purge(actor: FlowActor, input: {
+        flowId: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;

package/dist/http/http.js

@@ -1,6 +1,6 @@
-import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
+import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
-import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
 import { RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
@@ -360,6 +360,15 @@ export function createHttp(deps) {
         // Application behind an agent (#182). Every other kind never reaches it.
         return context.json(await deps.nodes.archive(asActor(auth), input));
     });
+    // ⚠️ DELETE, and it means it (#457). Every other "delete" in this surface is `archived_at`; this
+    // one leaves nothing behind. The same capability as archiving — `nodes.write` — because the
+    // structural guard is elsewhere: only an archived node can be purged, so the destructive way has
+    // two steps and the first one is reversible.
+    app.delete("/nodes/:nodeId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = PurgeNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        return context.json(await deps.nodes.purge(asActor(auth), input));
+    });
     app.get("/nodes/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "nodes", "share");
         return context.json(await deps.nodes.listGrants(asActor(auth), context.req.param("nodeId")));
@@ -475,6 +484,12 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.archive(asFlowActor(auth), input));
     });
+    // ⚠️ DELETE, and it means it (#457) — the flow's versions and the record of every run it had.
+    app.delete("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = PurgeFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.purge(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/versions", async (context) => {
         const auth = requireCapability(context, "flows", "write");
         const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));

package/dist/intel/intel.js

@@ -116,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/dist/mcp/mcp.js

@@ -1,7 +1,7 @@
 import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
-import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
+import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
-import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
 import { ListGrantsInput, RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
@@ -464,6 +464,26 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.archive(actor, input)));
+        // ⚠️ It exists on this surface for the reason #436 states: a way only the interface has is a way
+        // an agent goes around, by looking for the row in the database. What it may do is bounded by the
+        // same rules the interface obeys — only an archived node, only an empty folder, never one a flow
+        // still uses.
+        server.registerTool("node_purge", {
+            title: "Delete node for good",
+            description: "Delete one ARCHIVED node and everything belonging to it — every version, its content, its grants and its entries in the search index. This cannot be undone. A living node is refused: archive it first. A folder is refused while it still holds anything, and so is a node a published flow uses as a step; documents that merely LINK to it are not, and their links break.",
+            inputSchema: PurgeNodeInput,
+            annotations: {
+                title: "Delete node for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // ⚠️ NOT idempotent, and that is the honest answer rather than a missing flag: calling it
+                // twice deletes once and then answers 404. A client that repeated it on a timeout would
+                // otherwise read the second answer as "already done" when it may mean "somebody else's
+                // node with that id is gone".
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.purge(actor, input)));
     }
     if (permits(deps.authorization, "nodes", "share")) {
         server.registerTool("node_grant_list", {
@@ -689,6 +709,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.archive(flowActor, input)));
+        // ⚠️ On this surface because a way only the UI has is a way an agent works around (#436). Its
+        // limits are the same as the UI's.
+        server.registerTool("flow_purge", {
+            title: "Delete flow for good",
+            description: "Delete one ARCHIVED flow together with every version and the record of every run it had. This cannot be undone. A living flow is refused: archive it first. So is a flow another published flow still calls, and one whose runs started runs of other flows.",
+            inputSchema: PurgeFlowInput,
+            annotations: {
+                title: "Delete flow for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // Not idempotent, and that is the honest answer: twice deletes once and then answers 404.
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.purge(flowActor, input)));
         server.registerTool("flow_version_create", {
             title: "Create flow version",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",

package/dist/nodes/nodes.js

@@ -849,6 +849,87 @@ export function createNodes(deps) {
                 await deps.indexing.enqueue(updated.currentVersionId);
             return updated;
         },
+        /**
+         * ⚠️ The one call in Intel after which something is really gone (#457). Read the decisions on
+         * that issue before changing anything here: each refusal below is one of them, and each was
+         * chosen to the safer side.
+         */
+        async purge(actor, input) {
+            const node = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, input.nodeId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            // ⚠️ THE structural guard: only what is already archived may go. A stronger PERMISSION would
+            // not have made this safer, only rarer — whoever may archive can already make the content
+            // invisible. What makes it safe is that the destructive path has two steps and the first one
+            // is reversible.
+            if (!node.archivedAt) {
+                throw new IntelError(409, "node_not_archived", "Only an archived node can be deleted for good. Archive it first.");
+            }
+            // A folder is refused while anything is still inside — archived rows included. A cascade
+            // would turn ONE confirmed click into an unknown number of deletions, and the confirmation
+            // could then no longer name what disappears. `folder_execute_in_use` (#448) is the pattern:
+            // an answer with a reason beats an effect that reaches further than the question.
+            if (await deps.repository.hasAnyChild(node.id)) {
+                throw new IntelError(409, "folder_not_empty", "This folder still holds entries. Empty it before deleting it for good.");
+            }
+            // ⚠️ The other class of dependant, and the reason it refuses where a prose link does not: a
+            // flow would break at RUN TIME, in front of somebody who did not order this deletion.
+            //
+            // ⚠️ `flowsUsingNode`, NOT `externalFlowCallers` — the first version asked the second and
+            // therefore never refused anything (found in review). `externalFlowCallers` answers "who calls
+            // a FLOW filed inside this folder" (`kind: "subflow"`); a flow reads a NODE through a
+            // tree-link step (`configuration.resourceId`). Two different graph shapes, and only the second
+            // one is what a deleted document breaks.
+            const users = await deps.flowsUsingNode(actor, node.id);
+            if (users.visible.length || users.hidden) {
+                throw new IntelError(409, "node_in_use_by_flow", callersDetail(users));
+            }
+            // Not a refusal — a fact for the record. A prose reference is a mention, not an operation;
+            // refusing over one would make deleting a lottery, decided by whoever once linked to it. The
+            // surface names the number BEFORE the reader says yes.
+            const inboundLinks = await deps.repository.countInboundLinks(node.id);
+            // ⚠️ The vectors go FIRST, and the order is the correction of a wrong claim (found in review).
+            // The comment here used to say Vectorize needed no call because archiving had already emptied
+            // it. Archiving only ENQUEUES the purge, and that pass starts from `archivedNodeId(versionId)`
+            // — a join over `nodes`. Once this batch has run, that answers `null` and removes nothing,
+            // while `node_vectors`, the only record of what the vectors are CALLED, is gone with it. The
+            // orphans would then be unnameable forever, and each one keeps a place in the 100-candidate
+            // list Vectorize caps per installation.
+            //
+            // ⚠️ Before the batch rather than after, which inverts the order the content keys follow — and
+            // the rule behind both is the same: DO THE IRRECOVERABLE THING LAST. A failed batch after the
+            // vectors are gone leaves an ARCHIVED node whose index can be rebuilt (`reindex`); a failed
+            // removal after the batch leaves orphans nothing can name.
+            const vectorKeys = await deps.repository.listVectorKeys(node.id);
+            // The whole-node chunk carries the empty key and is never in the table — the pass writes it
+            // and records the rest, so a purge that only sent the recorded ones would leave it behind.
+            if (deps.semantic)
+                await deps.semantic.remove(node.id, ["", ...vectorKeys]);
+            const purged = await deps.repository.purgeNode({
+                nodeId: node.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+                // ⚠️ The title travels INTO the record from the row itself (the repository reads it there),
+                // and this is what travels beside it. After the delete nothing can look either up.
+                metadata: { inboundLinks },
+            });
+            // The row was restored or already gone between the check and the statement. Nothing was
+            // deleted, and saying so is better than reporting a success that did not happen.
+            if (purged === "missing") {
+                throw new IntelError(409, "update_conflict", "This node was changed by another editor");
+            }
+            // ⚠️ AFTER the database agreed, never before: it is the truth about what exists, and an object
+            // deleted ahead of a batch that then fails would leave a node whose content is gone.
+            //
+            // ⚠️ Vectorize needs no call here, and that follows from the guard above rather than from
+            // luck: archiving already takes a node's vectors out of the index (see `archive`), and only
+            // an archived node reaches this line. What is emptied above is Intel's own bookkeeping.
+            for (const key of purged.contentKeys)
+                await deps.content.delete(key);
+            return { purged: true, title: node.title };
+        },
         async listGrants(actor, resourceId) {
             const node = await requireVisible(actor, resourceId);
             if (!(await deps.repository.can(actor, resourceId, "share"))) {

package/dist/nodes/nodes.types.d.ts

@@ -84,6 +84,18 @@ export interface NodeRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Node>;
+    hasAnyChild(nodeId: string): Promise<boolean>;
+    listVectorKeys(nodeId: string): Promise<string[]>;
+    countInboundLinks(nodeId: string): Promise<number>;
+    purgeNode(input: {
+        nodeId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+        metadata: Record<string, unknown>;
+    }): Promise<"missing" | {
+        contentKeys: string[];
+    }>;
     listGrants(resourceId: string): Promise<ResourceGrant[]>;
     organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
     listLinksVisible(actor: Actor, nodeId: string): Promise<NodeLink[]>;
@@ -189,6 +201,19 @@ export interface NodesDeps {
         hidden: number;
     }>;
     flowNodeReferences(actor: Actor, folderId: string): Promise<string[]>;
+    /**
+     * Published flows that use THIS node as a step (#457).
+     *
+     * ⚠️ Not the same question as `externalFlowCallers`, and the difference cost a refusal that never
+     * fired: that one asks who calls a FLOW filed inside a folder (`kind: "subflow"`,
+     * `configuration.flowId`). A flow reads a NODE through a tree-link step (`configuration
+     * .resourceId`) — a different graph shape entirely, and the one a deletion breaks at run time, in
+     * front of somebody who did not order it.
+     */
+    flowsUsingNode(actor: Actor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
     /**
      * The handles of the MCP servers this actor reaches through the portal right now (D30).
      *
@@ -260,6 +285,12 @@ export interface NodeService {
      * is off, which stops working loudly and is repaired by repeating the call.
      */
     archive(actor: Actor, input: ArchiveNodeInput): Promise<Node>;
+    purge(actor: Actor, input: {
+        nodeId: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
     listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
     listLinks(actor: Actor, nodeId: string): Promise<{
         items: NodeLink[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.15.0",
-    "@anchrd/intel-contract": "^0.15.0",
+    "@anchrd/intel-contract": "^0.16.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",