@anchrd/intel 0.59.0

package/dist/http/http.js

@@ -0,0 +1,874 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { AuditListRequest } from "../contract/audit.js";
+import { BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, DirectoryResolveInput, } from "../contract/board.js";
+import { FeedListRequest } from "../contract/feed.js";
+import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "../contract/flow.js";
+import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "../contract/flow-run.js";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, MaxAttachmentBytes, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentBytesInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "../contract/node.js";
+import { RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, ShareInput, } from "../contract/share.js";
+import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, RedefineTableInput, UpdateTableRowsInput, } from "../contract/table.js";
+import { ExecuteToolInput, TestToolInput } from "../contract/tool.js";
+import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { intelProblem, problemDetails as problem, } from "../shared/problem-details/problem-details.js";
+import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
+// A query string is a door to the outside like a body is, so what arrives through it is closed
+// rather than tolerated: `z.strictObject` refuses an unknown field, and this is that refusal for the
+// half of the input Zod never sees. A silently ignored parameter is how a caller believes it asked
+// for something it did not get — a mistyped `limit=` that quietly draws everything, for instance.
+//
+// ⚠️ Not the same decision as `selectionSearch` in the UI, which deliberately passes unknown search
+// parameters through so the portal's return marker survives a redirect. That is a browser location;
+// this is an API route.
+function requireKnownQuery(url, allowed) {
+    const unknown = [];
+    url.searchParams.forEach((_value, key) => {
+        if (!allowed.includes(key))
+            unknown.push(key);
+    });
+    if (unknown.length) {
+        throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknown.join(", ")}`);
+    }
+}
+function asActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        isAdmin: authorization.can("intel", "admin"),
+    };
+}
+// The exporting caller: the node actor plus whether flows may ride along in the bundle at all.
+// Gate's `flows/read` is asked here once, so the bundle service never re-derives a capability.
+function asBundleActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        isAdmin: authorization.can("intel", "admin"),
+        canReadFlows: permits(authorization, "flows", "read"),
+        canCreateFlows: permits(authorization, "flows", "create"),
+    };
+}
+// The idempotency key of an import travels as a header: the body is the zip itself, so there is no
+// JSON envelope to put it in, and a query string would drag it into logs (#137).
+const ImportIdempotencyKey = z.string().min(8).max(200);
+// A bundle export streamed as a download. `content-length` is deliberately absent: the zip is
+// written while it leaves, which is the whole point of streaming it (#136).
+function zipResponse(bundle) {
+    return new Response(bundle.stream, {
+        headers: {
+            "cache-control": "private, no-store",
+            "content-disposition": contentDisposition(bundle.filename),
+            "content-type": "application/zip",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}
+function asToolActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        canExecute: permits(authorization, "tools", "execute"),
+    };
+}
+// RFC 5987 ext-value: encodeURIComponent leaves ' * ! ( ) unescaped, and a bare apostrophe is a
+// delimiter that would make the header ambiguous. The ASCII filename stays as a fallback.
+function contentDisposition(title) {
+    const encoded = encodeURIComponent(title).replace(/['()*!]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    const ascii = title.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+function asFlowActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        canRun: permits(authorization, "flows", "run"),
+        isAdmin: authorization.can("intel", "admin"),
+    };
+}
+export function createHttp(deps) {
+    const app = new Hono();
+    async function authenticated(headers) {
+        const token = bearer(headers) ?? (await deps.auth?.resolve(headers))?.bearer ?? null;
+        if (!token)
+            return null;
+        const authorization = await authorizeBearer(deps.gate, token, deps.resource);
+        return authorization ? { authorization, token } : null;
+    }
+    app.onError((error, context) => {
+        if (error instanceof IntelError) {
+            return context.json(intelProblem(error), error.status);
+        }
+        if (error instanceof z.ZodError) {
+            return context.json(problem(400, "invalid_request", "Request validation failed", z.prettifyError(error)), 400);
+        }
+        // Same rule as the outer app: an expected refusal explains itself, an unknown exception must
+        // leave a trace — otherwise the 500 is a fact without a reason anywhere (#93).
+        reportUnexpectedError(error);
+        return context.json(problem(500, "internal_error", "Internal server error"), 500);
+    });
+    app.use("*", async (context, next) => {
+        const session = await authenticated(context.req.raw.headers);
+        if (!session) {
+            context.header("WWW-Authenticate", `Bearer resource_metadata="${deps.resourceMetadataUrl}"`);
+            return context.json(problem(401, "authentication_required", "Authentication required"), 401);
+        }
+        context.set("authorization", session.authorization);
+        context.set("token", session.token);
+        await next();
+    });
+    function requireCapability(context, handle, fn) {
+        const authorization = context.get("authorization");
+        if (!permits(authorization, handle, fn)) {
+            throw new IntelError(403, "permission_required", "Permission required");
+        }
+        return authorization;
+    }
+    // The caller's own identity, so the shell can name who is signed in. It needs no capability —
+    // the answer is the token's own subject — and it returns nothing but id, email, and name.
+    app.get("/session", (context) => {
+        const authorization = context.get("authorization");
+        const { identity } = authorization;
+        return context.json({
+            id: identity.id,
+            email: identity.email,
+            name: identity.name ?? null,
+            // ⚠️ What the shell may DRAW, never what it may do (#416). Every admin route below still asks
+            // `requireCapability` for itself, and a browser that lied here would gain nothing but a
+            // button that answers 403.
+            isAdmin: authorization.can("intel", "admin"),
+        });
+    });
+    app.get("/nodes", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const url = new URL(context.req.url);
+        const unknownQuery = [];
+        url.searchParams.forEach((_value, key) => {
+            if (key !== "parentId" && key !== "includeArchived" && key !== "archivedOnly") {
+                unknownQuery.push(key);
+            }
+        });
+        if (unknownQuery.length) {
+            throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknownQuery.join(", ")}`);
+        }
+        const input = ListNodesInput.parse({
+            parentId: url.searchParams.get("parentId"),
+            includeArchived: url.searchParams.get("includeArchived") === "true",
+            ...(url.searchParams.get("archivedOnly") === "true" ? { archivedOnly: true } : {}),
+        });
+        return context.json(await deps.nodes.list(asActor(auth), input));
+    });
+    app.get("/nodes/graph", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const url = new URL(context.req.url);
+        const input = NodeGraphInput.parse({
+            limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        });
+        return context.json(await deps.nodes.graph(asActor(auth), input));
+    });
+    // ⚠️ Before `/nodes/:nodeId`, or the router would read "export" as a node ID. The root has no
+    // node to address, so the whole installation — as this caller may read it — exports here (#136).
+    app.get("/nodes/export", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), null));
+    });
+    // The reverse door (#137): a zip bundle — or a naked zipped folder — lands as a new subtree.
+    // The body IS the zip, streamed to the service rather than read whole here; `knowledge/create`
+    // like every other way of making nodes, and the resource-level write check is the service's.
+    async function importBundle(context, targetNodeId) {
+        const auth = requireCapability(context, "nodes", "create");
+        const idempotencyKey = ImportIdempotencyKey.parse(context.req.header("idempotency-key"));
+        const body = context.req.raw.body;
+        if (body === null) {
+            throw new IntelError(400, "invalid_request", "A zip request body is required");
+        }
+        const result = await deps.bundle.importBundle(asBundleActor(auth), {
+            targetNodeId,
+            zip: body,
+            idempotencyKey,
+        });
+        // A replay answers 200: nothing was created by THIS request, and the summary is the earlier
+        // import's. 201 stays the word for rows that exist because of this call.
+        return context.json(result, result.replayed ? 200 : 201);
+    }
+    // ⚠️ Before `/nodes/:nodeId`, or the router would read "import" as a node ID.
+    app.post("/nodes/import", async (context) => await importBundle(context, null));
+    app.get("/nodes/:nodeId", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        return context.json(await deps.nodes.get(asActor(auth), context.req.param("nodeId")));
+    });
+    app.post("/nodes/:nodeId/import", async (context) => {
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        return await importBundle(context, input.nodeId);
+    });
+    // One subtree — a folder with everything beneath it, or a single node — as a zip bundle (#136).
+    app.get("/nodes/:nodeId/export", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), input.nodeId));
+    });
+    // The change journal, read forward from a stable position (#620).
+    //
+    // ⚠️ **The capability follows the KIND asked for** (#774). An audit row says the same thing its
+    // resource says, so the journal asks what reading that resource asks: `nodes/read` for `node`,
+    // `flows/read` for `flow` and `flow-run` — which is what every other flow-delivering route in
+    // this file requires. Until the enum was widened one capability covered the one kind there was;
+    // leaving it at `nodes/read` afterwards would have dropped the first of the three checks for
+    // exactly the two kinds this ticket opened, and left the Intel ACL as the only filter.
+    //
+    // ⚠️ The parse therefore runs BEFORE the capability check, which is the one place in this file
+    // where it does. That is not a loosening of "capability first, so a refusal costs no storage
+    // read": parsing touches the query string and nothing else, and the kind cannot be known any
+    // earlier than this. What it costs is that a malformed `resourceType` answers 400 rather than
+    // 403 — a sentence about the caller's own parameter, which names nothing of Intel's.
+    //
+    // ⚠️ GET with the cursor in the query string, because the verb is one of the four in the grammar
+    // and the method carries it. `limit` arrives as a string and is coerced here — the contract
+    // wants a number, and a query string has none.
+    app.get("/audit", async (context) => {
+        const limit = context.req.query("limit");
+        const after = context.req.query("after");
+        const input = AuditListRequest.parse({
+            resourceType: context.req.query("resourceType"),
+            ...(after === undefined ? {} : { after }),
+            ...(limit === undefined ? {} : { limit: Number(limit) }),
+        });
+        const auth = requireCapability(context, input.resourceType === "node" ? "nodes" : "flows", "read");
+        return context.json(await deps.audit.list(asActor(auth), input));
+    });
+    // The same journal read the other way round: newest first, for a person rather than for a
+    // consumer catching up (#740).
+    //
+    // ⚠️ `nodes/read` for the whole answer, and here that CANNOT follow the kind the way `/audit`
+    // above does: one page mixes node and flow cards on purpose, so there is no single kind to pick a
+    // capability from. It has been that way since flow cards existed and #767 only added two actions
+    // to them, so nothing about it is new — but it does mean somebody holding `nodes/read` without
+    // `flows/read` still sees flow activity here, filtered by the Intel ACL alone. Narrowing it means
+    // filtering cards by capability inside the feed service, which is a change to the answer rather
+    // than to the door: #790.
+    //
+    // ⚠️ A SECOND door and not an option on `/audit`. That one is the contract `anchrd/signals` will
+    // build on, cursor and direction included; a shared signature would put both readers on one
+    // shape, and the next change to it would reach a consumer nobody had in mind.
+    app.get("/feed", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const limit = context.req.query("limit");
+        const before = context.req.query("before");
+        const actor = context.req.query("actor");
+        const input = FeedListRequest.parse({
+            ...(actor === undefined ? {} : { actor }),
+            ...(before === undefined ? {} : { before }),
+            ...(limit === undefined ? {} : { limit: Number(limit) }),
+        });
+        return context.json(await deps.feed.list(asActor(auth), input));
+    });
+    // The whole board in one answer (#648). `nodes/read` and nothing new: a board is a node, and a
+    // card is a node — a second capability would be a second answer to one question.
+    //
+    // ⚠️ Every filter is a query parameter and every one of them reaches the WHERE. Filtering after
+    // the read would have carried other people's cards over the wire first.
+    app.get("/boards/:boardId", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const query = context.req.query();
+        const input = BoardGetInput.parse({
+            boardId: context.req.param("boardId"),
+            ...(query.status === undefined ? {} : { status: query.status }),
+            ...(query.assigneeId === undefined ? {} : { assigneeId: query.assigneeId }),
+            ...(query.dueBefore === undefined ? {} : { dueBefore: query.dueBefore }),
+            ...(query.dependsOn === undefined ? {} : { dependsOn: query.dependsOn }),
+            ...(query.includeArchived === undefined
+                ? {}
+                : { includeArchived: query.includeArchived === "true" }),
+        });
+        return context.json(await deps.boards.get(asActor(auth), input));
+    });
+    /**
+     * Who this card may be given to (#700, D70).
+     *
+     * ⚠️ `nodes/read`, not a capability of its own and certainly not `nodes/write`. Offering an
+     * assignee is something everyone who can open the board does; a separate permission would be one
+     * more thing to grant before a picker works, and nothing would be safer for it — the answer is
+     * already narrower than what gate hands any signed-in person at its own door.
+     */
+    app.get("/boards/:boardId/assignees", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = BoardAssigneeSearchInput.parse({
+            boardId: context.req.param("boardId"),
+            query: context.req.query("q") ?? "",
+        });
+        return context.json(await deps.boards.searchAssignees(asActor(auth), input));
+    });
+    /**
+     * What the people already on cards are called (#258, #700).
+     *
+     * ⚠️ A POST although it reads, and for the same reason gate's own door is one: the ids travel in
+     * the body. A list of a hundred identifiers in a query string lands in proxy logs and in browser
+     * history, and it would hit the length limit long before the hundredth.
+     */
+    app.post("/directory/resolve", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = DirectoryResolveInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.boards.resolveNames(asActor(auth), input));
+    });
+    app.patch("/boards/:boardId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = BoardUpdateInput.parse(await context.req.json().catch(() => null));
+        if (input.boardId !== context.req.param("boardId")) {
+            throw new IntelError(400, "board_id_mismatch", "Path and body board IDs differ");
+        }
+        return context.json(await deps.boards.update(asActor(auth), input));
+    });
+    app.post("/boards/:boardId/tasks", async (context) => {
+        const auth = requireCapability(context, "nodes", "create");
+        const input = BoardTaskCreateInput.parse(await context.req.json().catch(() => null));
+        if (input.boardId !== context.req.param("boardId")) {
+            throw new IntelError(400, "board_id_mismatch", "Path and body board IDs differ");
+        }
+        return context.json(await deps.boards.createTask(asActor(auth), input), 201);
+    });
+    // ⚠️ `PATCH` on the task, not `POST …/move`. Moving a card IS an update of `status` and
+    // `position`; a second address for it would be a second way to write one row.
+    app.patch("/boards/:boardId/tasks/:taskId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = BoardTaskUpdateInput.parse(await context.req.json().catch(() => null));
+        if (input.taskId !== context.req.param("taskId")) {
+            throw new IntelError(400, "task_id_mismatch", "Path and body task IDs differ");
+        }
+        return context.json(await deps.boards.updateTask(asActor(auth), input));
+    });
+    app.get("/nodes/:nodeId/versions", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        return context.json(await deps.nodes.listVersions(asActor(auth), context.req.param("nodeId")));
+    });
+    // The content behind one row of the list above (#147): what a version-pinned citation points at.
+    // Read capability like every other node read; the resource ACL and the node/version pairing are
+    // the service's to refuse.
+    app.get("/nodes/:nodeId/versions/:versionId/content", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = GetNodeVersionInput.parse({
+            nodeId: context.req.param("nodeId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.nodes.getVersion(asActor(auth), input.nodeId, input.versionId));
+    });
+    // The metadata half of an attachment (#148): what `node_attachment_get` answers an agent, for
+    // HTTP callers who so far could only stream the bytes. Without the `resourceUri` — an MCP
+    // resource address says nothing to an HTTP client, whose address for the bytes is the sibling
+    // route below.
+    app.get("/nodes/:nodeId/attachment/meta", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        const { node, version } = await deps.nodes.getAttachment(asActor(auth), input.nodeId);
+        return context.json({ node, version });
+    });
+    app.get("/nodes/:nodeId/attachment", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const { attachment, body } = await deps.nodes.readAttachment(asActor(auth), context.req.param("nodeId"));
+        return new Response(body, {
+            headers: {
+                "cache-control": "private, no-store",
+                "content-disposition": contentDisposition(attachment.node.title),
+                "content-type": attachment.version.mediaType,
+                "x-content-type-options": "nosniff",
+            },
+        });
+    });
+    app.get("/nodes/:nodeId/table", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        return context.json(await deps.nodes.getTable(asActor(auth), context.req.param("nodeId")));
+    });
+    // Defining the header and appending rows are two routes because they are two decisions: the
+    // header is written once and is the contract, an append is the everyday write (#40).
+    app.post("/nodes/:nodeId/table", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = DefineTableInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.defineTable(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/table/rows", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = AppendTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.appendTableRows(asActor(auth), input), 201);
+    });
+    // The three mutations beside the append (#135). Action-style POSTs like the archive and revoke
+    // routes, because a row has no address of its own to PUT to: positions live in the body, next to
+    // the `baseVersionId` that says which state they mean. Each writes one snapshot version, so the
+    // 201 is the same statement the append's 201 makes.
+    app.post("/nodes/:nodeId/table/rows/update", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = UpdateTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.updateTableRows(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/table/rows/delete", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = DeleteTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.deleteTableRows(asActor(auth), input), 201);
+    });
+    app.patch("/nodes/:nodeId/table", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = RedefineTableInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.redefineTable(asActor(auth), input), 201);
+    });
+    // ⚠️ There is deliberately no route for the sixth board operation. `board_repair_task_ids`
+    // (anchrd/intel#341) is MCP-only until a screen calls it: the routes here are what the browser
+    // reaches, nothing in `intel-data-provider` asks for it, and a route with no caller is the thing
+    // YAGNI is about. The screen is anchrd/intel#358, and it brings this route with it.
+    app.get("/nodes/:nodeId/links", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        return context.json(await deps.nodes.listLinks(asActor(auth), context.req.param("nodeId")));
+    });
+    // A document link's name, for whoever is reading the text (#41). A POST because the list of IDs
+    // is the request body — putting them in a query string would put the tree's identifiers into
+    // logs and referrers. The `knowledge/read` capability and nothing more: it answers with what this reader may
+    // already see, and stays silent about the rest rather than saying that there is a rest.
+    //
+    // There is no route to create or delete a link any more. A relationship is written where it is
+    // meant, in the text, and `POST /nodes/:nodeId/versions` is what records it.
+    app.post("/nodes/links/resolve", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = ResolveNodeLinksInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.resolveLinks(asActor(auth), input));
+    });
+    app.post("/nodes/search", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = SearchInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.search(asActor(auth), input));
+    });
+    app.post("/nodes/reindex", async (context) => {
+        const auth = requireCapability(context, "intel", "admin");
+        z.strictObject({}).parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.reindex(asActor(auth)), 202);
+    });
+    app.post("/nodes", async (context) => {
+        const auth = requireCapability(context, "nodes", "create");
+        const input = CreateNodeInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.create(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/versions", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = SaveNodeVersionInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.save(asActor(auth), input), 201);
+    });
+    /**
+     * The streaming door for a file (#821): the body IS the bytes, and everything about them travels
+     * in the headers the request already has.
+     *
+     * ⚠️ **It has no MCP twin on purpose**, and it is the one capability in this file that does not.
+     * MCP carries JSON, so a tool cannot hand over a body; `node_attachment_create` remains the MCP
+     * form of the same act, with the base64 size limit that door brings with it. What must not happen
+     * is a second set of RULES here — the checks are the service's, and both doors call the same one.
+     *
+     * ⚠️ `intel-base-version-id` carries what `baseVersionId` carries in the JSON door, and the word
+     * `none` is how a first upload says "there is no version yet". An absent header is refused rather
+     * than read as `none`: a caller who merely forgot it would otherwise overwrite the newest version
+     * instead of being told that somebody else wrote first — which is the whole point of the field.
+     *
+     * ⚠️ The length is refused BEFORE the body is read, from `content-length`. A file over the limit
+     * has to end in a sentence the reader gets, and a request that has already been read to its end
+     * cannot be answered with one on every client.
+     */
+    app.post("/nodes/:nodeId/attachment/bytes", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const baseVersionHeader = context.req.header("intel-base-version-id");
+        if (baseVersionHeader === undefined) {
+            throw new IntelError(400, "invalid_request", 'intel-base-version-id takes the current version id, or "none" for the first upload');
+        }
+        const declared = Number(context.req.header("content-length"));
+        if (!Number.isSafeInteger(declared) || declared <= 0) {
+            throw new IntelError(411, "length_required", "An upload has to announce its length in content-length");
+        }
+        if (declared > MaxAttachmentBytes) {
+            throw new IntelError(413, "attachment_too_large", `An attachment may carry at most ${MaxAttachmentBytes} bytes`);
+        }
+        const input = SaveAttachmentBytesInput.parse({
+            nodeId: context.req.param("nodeId"),
+            baseVersionId: baseVersionHeader === "none" ? null : baseVersionHeader,
+            mediaType: context.req.header("content-type") ?? "",
+            size: declared,
+            idempotencyKey: ImportIdempotencyKey.parse(context.req.header("idempotency-key")),
+        });
+        const body = context.req.raw.body;
+        if (body === null) {
+            throw new IntelError(400, "invalid_request", "A request body is required");
+        }
+        return context.json(await deps.nodes.saveAttachmentBytes(asActor(auth), input, body), 201);
+    });
+    app.post("/nodes/:nodeId/attachment", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = SaveAttachmentInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.saveAttachment(asActor(auth), input), 201);
+    });
+    app.patch("/nodes/:nodeId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = UpdateNodeInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.update(asActor(auth), input));
+    });
+    app.post("/nodes/:nodeId/archive", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = ArchiveNodeInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        // The caller's own bearer, for the one thing archiving may have to do in Gate: switch off the
+        // 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(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.purge(asActor(auth), input));
+    });
+    app.get("/nodes/:nodeId/purge-preview", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = PurgeNodePreviewInput.parse({ nodeId: context.req.param("nodeId") });
+        return context.json(await deps.nodes.purgePreview(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")));
+    });
+    app.get("/nodes/:nodeId/effective-access", async (context) => {
+        const auth = requireCapability(context, "nodes", "share");
+        return context.json(await deps.nodes.listEffectiveAccess(asActor(auth), context.req.param("nodeId")));
+    });
+    app.post("/nodes/:nodeId/grants", async (context) => {
+        const auth = requireCapability(context, "nodes", "share");
+        const input = ShareInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body resource IDs differ");
+        }
+        return context.json(await deps.nodes.share(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/grants/:grantId/revoke", async (context) => {
+        const auth = requireCapability(context, "nodes", "share");
+        const input = RevokeGrantInput.parse(await context.req.json().catch(() => null));
+        if (input.resourceId !== context.req.param("nodeId") ||
+            input.grantId !== context.req.param("grantId")) {
+            throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
+        }
+        return context.json(await deps.nodes.revokeGrant(asActor(auth), input));
+    });
+    app.get("/flows", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["parentId", "includeArchived", "archivedOnly"]);
+        // Absent means "every flow I may see"; present but empty means the root of the shared tree.
+        // Without that distinction a tree level and a full list would be the same request.
+        const parentId = url.searchParams.get("parentId");
+        // Same rule for the archive: absent means "without it". Spelling the default out would put a
+        // field into every call that asks nothing about the archive.
+        const input = ListFlowsInput.parse({
+            ...(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {}),
+            ...(url.searchParams.get("includeArchived") === "true" ? { includeArchived: true } : {}),
+            ...(url.searchParams.get("archivedOnly") === "true" ? { archivedOnly: true } : {}),
+        });
+        return context.json(await deps.flows.list(asFlowActor(auth), input));
+    });
+    // ⚠️ Before `/flows/:flowId`, or the router would read "graph" as a flow ID. Same order and same
+    // reason as `/nodes/graph`.
+    app.get("/flows/graph", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["of", "folderId", "flowId", "limit"]);
+        const of = url.searchParams.get("of");
+        const input = RelationGraphInput.parse({
+            scope: of === "flow"
+                ? { of: "flow", flowId: url.searchParams.get("flowId") ?? "" }
+                : { of: "folder", folderId: url.searchParams.get("folderId") || null },
+            limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        });
+        return context.json(await deps.flows.relationGraph(asFlowActor(auth), input));
+    });
+    // A path variable is a door like any other, so it is parsed rather than trusted: `GetFlowInput`
+    // is the same schema the body-carrying routes and the MCP tools use for this identifier.
+    app.get("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.get(asFlowActor(auth), input.flowId));
+    });
+    /**
+     * A single flow as the same bundle shape a node export makes: one entry plus the manifest
+     * (#136). `flows/read` like every other read of the graph.
+     *
+     * ⚠️ Deliberately no `flow_export` tool beside it, and the reason is NOT the one `node_export`
+     * carries (#436). There the memory argument decides — a subtree's zip would have to fit in Worker
+     * memory twice — and a flow bundle is one entry plus the manifest, so that argument does not
+     * reach here.
+     *
+     * What decides here is that the manifest of ONE entry answers nothing MCP does not already
+     * answer. `node_export` is worth a tool because its manifest is the PLAN of a subtree: every
+     * readable entry with its path, kind and media type, which is the map for fetching each one. For
+     * a single flow that map has one row, whose id the caller already holds — and the substance, the
+     * graph, is `flow_version_get` and `flow_graph`, with the record itself in `flow_get`. A tool
+     * whose whole answer is two other tools' answers costs bytes in every `tools/list` and makes the
+     * other names less reliable as a guide, which `packages/intel/CLAUDE.md` treats as the cost it is.
+     *
+     * ⚠️ This is not the case `.claude/rules/destructive.md` warns about — "a way only the surface
+     * has is a way an agent works around". Nothing about a flow is unreachable over MCP; only the zip
+     * CONTAINER is HTTP-only, exactly as it is for nodes. `mcp.e2e.ts` pins that this exception is
+     * named rather than merely absent.
+     */
+    app.get("/flows/:flowId/export", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return zipResponse(await deps.bundle.exportFlow(asBundleActor(auth), input.flowId));
+    });
+    // What this flow calls, read out of its graph. The tree lists where a flow is filed; this lists
+    // what it runs, and a shared subflow answers both questions at once (ADR-0004 §3).
+    app.get("/flows/:flowId/calls", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listCalls(asFlowActor(auth), input.flowId));
+    });
+    // Would this flow start, for whoever is asking, right now (#72). `flows/read` and nothing more:
+    // the answer somebody without `execute` needs most is that they are missing `execute`, and it
+    // names nothing they could not read out of the graph. A GET because it changes nothing — no run,
+    // no key, no audit event.
+    app.get("/flows/:flowId/validation", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.validate(asFlowActor(auth), input.flowId));
+    });
+    // What this flow needs: the documents and tools its graph names. `flows/read` and nothing more —
+    // it describes a flow the caller may already open, and names only what they may already see.
+    app.get("/flows/:flowId/requirements", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listRequirements(asFlowActor(auth), input.flowId));
+    });
+    // The flow's own sharing (#530), segment for segment the node routes one screen up. `flows/share`
+    // was declared to Gate from the beginning and had no consumer until now; these four are it.
+    app.get("/flows/:flowId/grants", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        return context.json(await deps.flows.listGrants(asFlowActor(auth), context.req.param("flowId")));
+    });
+    app.get("/flows/:flowId/effective-access", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        return context.json(await deps.flows.listEffectiveAccess(asFlowActor(auth), context.req.param("flowId")));
+    });
+    app.post("/flows/:flowId/grants", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        const input = ShareFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.share(asFlowActor(auth), input), 201);
+    });
+    app.post("/flows/:flowId/grants/:grantId/revoke", async (context) => {
+        const auth = requireCapability(context, "flows", "share");
+        const input = RevokeFlowGrantInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId") ||
+            input.grantId !== context.req.param("grantId")) {
+            throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
+        }
+        return context.json(await deps.flows.revokeGrant(asFlowActor(auth), input));
+    });
+    app.post("/flows", async (context) => {
+        const auth = requireCapability(context, "flows", "create");
+        const input = CreateFlowInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.flows.create(asFlowActor(auth), input), 201);
+    });
+    app.patch("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = UpdateFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.update(asFlowActor(auth), input));
+    });
+    // `flows/write`, the same capability renaming and moving need: archiving is organization, not a
+    // change to what the flow does.
+    app.post("/flows/:flowId/archive", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = ArchiveFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        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));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.save(asFlowActor(auth), input), 201);
+    });
+    // The GET beside `POST /flows/:flowId/versions`: the same collection, read instead of appended
+    // to (#144). `flows/read` like `GET /flows/:flowId` — the history describes a flow the caller
+    // may already open.
+    app.get("/flows/:flowId/versions", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listVersions(asFlowActor(auth), input.flowId));
+    });
+    app.get("/flows/:flowId/versions/:versionId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowVersionInput.parse({
+            flowId: context.req.param("flowId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.flows.getVersion(asFlowActor(auth), input));
+    });
+    // What publishing would freeze, before it is published (ADR-0004 §5). A GET because it reads and
+    // changes nothing; the `publish` capability because it answers a question only a publisher has.
+    app.get("/flows/:flowId/versions/:versionId/publish-preview", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = PreviewFlowPublishInput.parse({
+            flowId: context.req.param("flowId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.flows.previewPublish(asFlowActor(auth), input));
+    });
+    app.post("/flows/:flowId/publish", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = PublishFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.publish(asFlowActor(auth), input));
+    });
+    // The reverse of publish, behind the same capability: whoever may publish may withdraw (#146).
+    app.post("/flows/:flowId/unpublish", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = UnpublishFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.unpublish(asFlowActor(auth), input));
+    });
+    app.post("/flows/:flowId/runs", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = StartFlowRunInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.start(asFlowActor(auth), input), 201);
+    });
+    // What this flow has done (#35). A GET beside `POST /flows/:flowId/runs`: the same collection,
+    // read instead of appended to. `flows/read` is the capability, and which of the runs actually
+    // appear is the resource rule the service applies per row.
+    app.get("/flows/:flowId/runs", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["failedOnly", "limit", "cursor"]);
+        const input = ListFlowRunsInput.parse({
+            flowId: context.req.param("flowId"),
+            // Present means "only the failed ones". A query string carries no booleans, so the parameter's
+            // presence is the flag rather than a string that would have to be spelled exactly right.
+            ...(url.searchParams.has("failedOnly") ? { failedOnly: true } : {}),
+            ...(url.searchParams.has("limit") ? { limit: Number(url.searchParams.get("limit")) } : {}),
+            ...(url.searchParams.has("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+        });
+        return context.json(await deps.flows.listRuns(asFlowActor(auth), input));
+    });
+    /**
+     * The same list across every flow (#774) — "did anything run", which used to take one call per
+     * flow and therefore went unasked.
+     *
+     * ⚠️ It sits at the root beside the other three run routes rather than under a flow, and the
+     * reason is the one already written for them in `packages/intel/CLAUDE.md`: reading, cancelling and
+     * completing a run do not need the flow, and a run outlives it. Naming no flow is exactly that
+     * case. One tool answers both addresses — `flow_run_list` with `flowId: null` — which is the same
+     * many-to-one the attachment routes have.
+     */
+    app.get("/flow-runs", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["failedOnly", "limit", "cursor"]);
+        const input = ListFlowRunsInput.parse({
+            flowId: null,
+            ...(url.searchParams.has("failedOnly") ? { failedOnly: true } : {}),
+            ...(url.searchParams.has("limit") ? { limit: Number(url.searchParams.get("limit")) } : {}),
+            ...(url.searchParams.has("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+        });
+        return context.json(await deps.flows.listRuns(asFlowActor(auth), input));
+    });
+    app.get("/flow-runs/:runId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowRunInput.parse({ runId: context.req.param("runId") });
+        return context.json(await deps.flows.getRun(asFlowActor(auth), input.runId));
+    });
+    // The drill-down behind the list: which step of this run ended it, and what it said.
+    app.get("/flow-runs/:runId/steps", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowRunInput.parse({ runId: context.req.param("runId") });
+        return context.json(await deps.flows.listRunSteps(asFlowActor(auth), input.runId));
+    });
+    app.post("/flow-runs/:runId/steps/complete", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = CompleteFlowRunStepInput.parse(await context.req.json().catch(() => null));
+        if (input.runId !== context.req.param("runId")) {
+            throw new IntelError(400, "run_id_mismatch", "Path and body run IDs differ");
+        }
+        return context.json(await deps.flows.completeStep(asFlowActor(auth), input));
+    });
+    // `flows/run`, the same capability the start asked for: whoever may start a run may end it
+    // (#145). The resource-level `execute` is the service's question, asked against the flow.
+    app.post("/flow-runs/:runId/cancel", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = CancelFlowRunInput.parse(await context.req.json().catch(() => null));
+        if (input.runId !== context.req.param("runId")) {
+            throw new IntelError(400, "run_id_mismatch", "Path and body run IDs differ");
+        }
+        return context.json(await deps.flows.cancelRun(asFlowActor(auth), input));
+    });
+    app.get("/tools", async (context) => {
+        const auth = requireCapability(context, "tools", "read");
+        return context.json(await deps.tools.catalog(asToolActor(auth)));
+    });
+    // ⚠️ Registered before `/tools/test` and `/tools/execute` and behind `tools/read`, not a new
+    // capability: it answers strictly less than `/tools` does — the servers behind the same live
+    // list, with no schemas (D30).
+    app.get("/tools/servers", async (context) => {
+        const auth = requireCapability(context, "tools", "read");
+        return context.json(await deps.tools.servers(asToolActor(auth)));
+    });
+    app.post("/tools/test", async (context) => {
+        const auth = requireCapability(context, "tools", "test");
+        const input = TestToolInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.tools.test(asToolActor(auth), input));
+    });
+    app.post("/tools/execute", async (context) => {
+        const auth = requireCapability(context, "tools", "execute");
+        const input = ExecuteToolInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.tools.execute(asToolActor(auth), input));
+    });
+    return app;
+}