@anchrd/intel-api 0.23.0 → 0.25.0

package/dist/cli/cli.js

@@ -1,38 +1,81 @@
 import { createBuild } from "../build/build.js";
 import { createPrepare } from "../prepare/prepare.js";
 const interfaces = [
-    { handle: "intel", functions: ["use", "admin"] },
+    // ⚠️ No `use`. Nothing asked it (#475): every door in Intel asks a concrete capability —
+    // `nodes:read`, `flows:run`, `mcp:connect` — and a coarse "may use Intel at all" beside them is a
+    // permission an operator sets and nothing consults. Worse than useless: somebody granted only
+    // `intel:use` gets the empty screen the README warns about and reads it as a defect.
+    // `admin` stays and is the opposite case — it is the one way into a tree that carries no grant
+    // yet (ADR-0004 §6), read in ten places.
+    { handle: "intel", functions: ["admin"] },
     // ⚠️ `nodes`, not `knowledge` — and the rename cost something, which is why it needed its own
     // ticket (#152) five months after #125 renamed everything else. This handle is only half Intel's:
-    // `bootstrap` DECLARES it in Gate and deliberately changes no grant, so to Gate a renamed handle
-    // is a NEW one. Every grant on the old name keeps pointing at the old name, and everybody loses
-    // access at once, silently, until an operator hands the permissions out again.
+    // `bootstrap` DECLARES it in Gate and touches no grant on an interface it does not name, so to
+    // Gate a renamed handle is a NEW one. Every grant on the old name keeps pointing at the old name,
+    // and everybody loses access at once, silently, until an operator hands the permissions out again.
     //
     // It was done in the one window where that is free: the installation on anchrd.sh was being
     // rebuilt anyway (#385, anchrd/core#93) and there is no other. Doing it later would mean doing it
     // to somebody.
     //
-    // ⚠️ The old `knowledge` interface stays declared in Gate — bootstrap declares, it never revokes.
-    // It is a harmless leftover on installations that have it, and nothing in Intel asks about it any
-    // more; removing it is an act in Gate, by hand, when somebody is sure nothing else uses it.
+    // ⚠️ The old `knowledge` interface stays declared in Gate — bootstrap declares only the handles in
+    // this list and never revokes a whole INTERFACE. It is a harmless leftover on installations that
+    // have it, and nothing in Intel asks about it any more; removing it is an act in Gate, by hand,
+    // when somebody is sure nothing else uses it.
     { handle: "nodes", functions: ["read", "create", "write", "share"] },
     // ⚠️ No `approve`. The approval node is gone (#73), and this list is what Intel declares to Gate:
-    // a function nobody asks about is a permission an operator has to decide on for no reason. An
-    // installation that already granted it keeps a harmless leftover — bootstrap declares, it does
-    // not revoke.
+    // a function nobody asks about is a permission an operator has to decide on for no reason.
+    //
+    // ⚠️ Dropping a FUNCTION from a still-declared interface is not the harmless leftover the two
+    // blocks around this one describe (#474). `gate.set` is `PUT /api/v1/service/interfaces/:handle`,
+    // an upsert that REPLACES the function list, and in the same batch Gate runs `obsoleteGrants` —
+    // `DELETE FROM grants WHERE interface_id = ? AND function NOT IN (…)`. Gate holds that down with
+    // a test of its own (`service-interfaces.int.ts`, "scoped set/remove per App-Key und entfernt
+    // Grants gestrichener Funktionen"), and it is right to: catalog and grants are one change against
+    // Gate's own reasoning above `obsoleteGrants`. So an installation that granted `approve` does
+    // NOT keep it — the next bootstrap deletes every role assignment on it. That is why bootstrap
+    // reads the current list before it writes and names what it takes away.
     {
         handle: "flows",
         functions: ["read", "create", "write", "publish", "run", "share"],
     },
-    { handle: "tools", functions: ["read", "test", "execute", "admin"] },
-    // ⚠️ `agents:run` is deliberately NOT here any more (#390). `bootstrap` declares, it never
-    // revokes, so an installation that has the interface keeps it as a harmless leftover — but a new
-    // one is not asked to decide about a permission nothing reads.
+    // ⚠️ No `admin`. Nothing asked it either (#475), and here the reason is architectural rather than
+    // an oversight: the Cloudflare MCP Portal owns which servers exist and who may reach each one, and
+    // Intel stores no tool permissions at all — the catalog is a live `tools/list` with the asking
+    // person's token. There is no administration of tools inside Intel for the function to guard, so
+    // it cannot grow a reader later without that boundary moving first.
+    { handle: "tools", functions: ["read", "test", "execute"] },
+    // ⚠️ `agents:run` is deliberately NOT here any more (#390). The whole `agents` handle left the
+    // list, and bootstrap writes only the handles it names, so an installation that has that
+    // interface keeps it and its grants as a harmless leftover — but a new one is not asked to decide
+    // about a permission nothing reads. ⚠️ This holds because a whole INTERFACE went; a single
+    // function taken out of a handle that is still listed here is deleted along with its grants, see
+    // the block above (#474).
     // `mcp:connect` means the same thing at every MCP service of this installation. A separate name
     // for the same thing forces the operator to check, service by service, which permission carries
     // portal access.
     { handle: "mcp", functions: ["connect"] },
 ];
+// What Intel used to declare and no longer does, keyed by handle for a whole interface and by
+// `handle:function` for a single function.
+//
+// ⚠️ It exists because "surplus: approve" is not actionable on its own (#466). An operator who reads
+// only the name has to decide whether somebody meant it, and the cheapest way out of that decision
+// is to leave it standing — which is how `approve` outlived #73 by months. The reason is the half
+// that turns the note into a decision instead of a puzzle, so a new retirement belongs in here in
+// the same pull request that takes its entry out of `interfaces` above.
+const retired = {
+    knowledge: "the whole interface became `nodes` (#152, after #125).",
+    agents: "the whole interface went when Agents left the surface (#390, #388).",
+    "flows:approve": "the approval node is gone (#73).",
+    "intel:use": "no door ever asked it; every one of them asks a concrete capability (#475).",
+    "tools:admin": "the portal owns tool administration, so Intel never had anything to guard (#475).",
+};
+// An unlisted surplus gets a sentence too. "no reason recorded" is an answer an operator can act on;
+// an empty dash reads as an omission and sends them looking for the missing half.
+function reason(key) {
+    return retired[key] ?? "no reason is recorded here, so read the history before removing it.";
+}
 const usage = `Usage: intel <prepare|bootstrap|build|doctor|reindex>
   intel prepare    Copy versioned D1 migrations to .intel/migrations
   intel bootstrap  Idempotently declare Intel interfaces in Gate
@@ -67,13 +110,41 @@ export function createCli(deps) {
             return fail("GATE_URL and GATE_SERVICE_KEY must be set.");
         }
         const gate = deps.createGateInterfaces(gateUrl, serviceKey);
-        for (const entry of interfaces)
+        // ⚠️ Read before writing, and refuse if the read fails. The current list is the only place the
+        // functions Gate is about to lose are named; `set` replaces it, and afterwards nothing can say
+        // which grants went with them (#474). A run that writes anyway takes permissions away and has
+        // nothing left to report — the old "No grants were changed." in exactly the shape that made it
+        // wrong. Bootstrap is idempotent, so refusing costs a second run.
+        let current;
+        try {
+            current = await within(gate.list());
+        }
+        catch {
+            return fail("Gate interfaces could not be read, so bootstrap cannot say which grants it would delete.");
+        }
+        let removed = 0;
+        for (const entry of interfaces) {
+            const declared = entry.functions;
+            const dropped = (current.find((row) => row.handle === entry.handle)?.functions ?? []).filter((fn) => !declared.includes(fn));
             await gate.set(entry.handle, [...entry.functions]);
-        deps.log(`Declared ${interfaces.length} Intel interfaces in Gate. No grants were changed.`);
+            // Logged per interface, right after its own write returned, so a run that fails halfway still
+            // named every deletion it actually caused.
+            if (dropped.length) {
+                removed += dropped.length;
+                const names = dropped.map((fn) => `${entry.handle}:${fn}`).join(", ");
+                deps.log(`Removed ${names} from Gate; every grant on ${dropped.length === 1 ? "it" : "them"} was deleted with it.`);
+            }
+        }
+        deps.log(`Declared ${interfaces.length} Intel interfaces in Gate.`);
+        if (!removed)
+            deps.log("No declared function was dropped, so Gate deleted no grant.");
         return 0;
     }
     async function doctor() {
         const failures = [];
+        // A surplus hinders nothing, so it is never a `FAIL`: a doctor one knows red is a doctor nobody
+        // reads, and then the next real failure goes with it (#466).
+        const notes = [];
         const gateUrl = envValue("GATE_URL");
         const intelUrl = envValue("INTEL_URL");
         const serviceKey = envValue("GATE_SERVICE_KEY") ?? envValue("GATE_KEY");
@@ -106,17 +177,44 @@ export function createCli(deps) {
         if (gateUrl && serviceKey) {
             try {
                 const current = await within(deps.createGateInterfaces(gateUrl, serviceKey).list());
+                let surplusFunction = false;
                 for (const expected of interfaces) {
                     const actual = current.find((entry) => entry.handle === expected.handle);
                     const missing = expected.functions.filter((fn) => !actual?.functions.includes(fn));
                     if (missing.length)
                         failures.push(`Gate interface ${expected.handle} misses ${missing}`);
+                    const declared = expected.functions;
+                    for (const fn of actual?.functions ?? []) {
+                        if (declared.includes(fn))
+                            continue;
+                        surplusFunction = true;
+                        notes.push(`Gate carries ${expected.handle}:${fn}, which Intel does not declare — ${reason(`${expected.handle}:${fn}`)}`);
+                    }
+                }
+                // ⚠️ The other direction, and it is the half a loop over `interfaces` can never reach: a
+                // handle Intel stopped declaring appears in no expectation, so it is never looked up. The
+                // comparison runs both ways or it does not run (#466).
+                const declaredHandles = interfaces.map((entry) => entry.handle);
+                const surplusHandles = current.filter((row) => !declaredHandles.includes(row.handle));
+                for (const row of surplusHandles) {
+                    notes.push(`Gate carries the interface ${row.handle} (${row.functions.join(", ")}), which Intel does not declare — ${reason(row.handle)}`);
+                }
+                // What to do about it, once per kind — because the two kinds need opposite acts. A surplus
+                // FUNCTION on a still-declared handle disappears by itself on the next `bootstrap`, grants
+                // and all (#474); a surplus HANDLE is never written and therefore never goes away on its own.
+                if (surplusFunction) {
+                    notes.push("The next `intel bootstrap` removes a surplus function and every grant on it (#474). Take the grant away in Gate first if anybody should keep it.");
+                }
+                if (surplusHandles.length) {
+                    notes.push("`bootstrap` never touches an interface Intel does not declare, so a surplus one stays until somebody removes it in Gate by hand — which takes its grants with it.");
                 }
             }
             catch {
                 failures.push("Gate interface check failed");
             }
         }
+        for (const note of notes)
+            deps.log(`NOTE ${note}`);
         if (failures.length) {
             for (const failure of failures)
                 deps.log(`FAIL ${failure}`);

package/dist/flows/flows.js

@@ -1,4 +1,5 @@
 import { flowNodeLayer } from "@anchrd/intel-contract/flow";
+import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
 function invalid(detail) {
@@ -7,6 +8,27 @@ function invalid(detail) {
 // A call chain deeper than this is a runaway rather than a design. It also bounds the publish-time
 // walk and the run trail, both of which follow data that other writers can change.
 const MaxCallDepth = 20;
+// All four, and unlike a node this needs no lookup: every verb means something on a flow. `read`
+// opens it, `write` edits it, `execute` runs it, `share` passes access on (#530).
+const flowVerbs = ["read", "write", "execute", "share"];
+/**
+ * The grantee as the ACL sees them, and as nothing else: an identity with no capability of its own.
+ *
+ * ⚠️ Never `isAdmin` and never `canRun`. Whether Gate hands this person `intel/admin` or `flows/run`
+ * is Gate's to know, so the warning built on this can be pessimistic and never permissive — it may
+ * say "they will not be able to reach this" about somebody who turns out to be able to. The other
+ * direction would be a warning that stays silent about a real gap.
+ *
+ * A grant to an email address is judged as that address, which is what the grant will be attached
+ * to; a second grant the same person holds under their user id is not folded in.
+ */
+function asPrincipalActor(principal) {
+    if (principal.type === "user")
+        return { id: principal.id, email: "", canRun: false };
+    if (principal.type === "email")
+        return { id: "", email: principal.email, canRun: false };
+    return { id: "", email: "", canRun: false };
+}
 // The four link kinds that name something in the shared tree (D25). `tool` is a link too, but it
 // names a portal tool rather than a resource, and every rule about reachability applies to these
 // four and not to it.
@@ -91,9 +113,22 @@ function toolStepDetail(missing) {
 }
 export function compileFlow(graph) {
     const nodes = new Map();
+    // ⚠️ A refusal names a node the way the canvas does — by its label — because the id appears
+    // nowhere on screen. `Node n-doc is a link and must be attached to a step` sent an author looking
+    // for a string the editor never draws, and the way to the cause led through the contract schema
+    // instead of through the sentence (#508). The id stays beside it: a graph arrives over MCP as
+    // readily as from the canvas, and there the id is what the caller holds.
+    //
+    // ⚠️ It stands ABOVE the loop that fills the map on purpose, so the duplicate-id refusal reaches
+    // it too — that one names the node the map already holds, which is the FIRST of the two. An id
+    // nothing knows falls back to the bare id, which is what the dangling-edge case wants anyway.
+    const named = (id) => {
+        const node = nodes.get(id);
+        return node ? `"${node.label}" (${id})` : id;
+    };
     for (const node of graph.nodes) {
         if (nodes.has(node.id))
-            invalid(`Duplicate node ID: ${node.id}`);
+            invalid(`Duplicate node ID: ${named(node.id)}`);
         nodes.set(node.id, node);
     }
     // ⚠️ Every arity rule below counts flow edges only. A context edge says "this belongs to that
@@ -116,7 +151,7 @@ export function compileFlow(graph) {
             // One holder per attached node: two steps claiming the same material would make "what does
             // this step work with" answerable two ways, and the second answer would never be shown.
             if (attachedTo.has(edge.target))
-                invalid(`Node ${edge.target} is already attached to ${attachedTo.get(edge.target)}`);
+                invalid(`Node ${named(edge.target)} is already attached to ${named(attachedTo.get(edge.target) ?? "")}`);
             attachedTo.set(edge.target, edge.source);
             attachments.set(edge.source, [...(attachments.get(edge.source) ?? []), edge]);
             continue;
@@ -147,44 +182,44 @@ export function compileFlow(graph) {
         // Before this, a link could stand in the chain — which is how a start with an attachment once
         // began its run at the attachment (#37).
         if (layer === "link" && holderId === undefined) {
-            invalid(`Node ${node.id} is a link and must be attached to a step`);
+            invalid(`Node ${named(node.id)} is a link and must be attached to a step`);
         }
         if (layer !== "link" && holderId !== undefined) {
-            invalid(`Node ${node.id} is not a link and cannot be attached to another node`);
+            invalid(`Node ${named(node.id)} is not a link and cannot be attached to another node`);
         }
         if (holderId !== undefined) {
             if (parents !== 0 || children.length !== 0) {
-                invalid(`Node ${node.id} is attached as context and cannot also be a step`);
+                invalid(`Node ${named(node.id)} is attached as context and cannot also be a step`);
             }
             const holder = nodes.get(holderId);
             // Only a step holds material. A marker carries nothing at all, and a `subflow` is a call: the
             // flow it names brings its own links, and lending it one from here would be steering another
             // flow from outside.
             if (holder && (flowNodeLayer[holder.kind] !== "step" || holder.kind === "subflow")) {
-                invalid(`Node ${node.id} can only be attached to an instruction or a condition`);
+                invalid(`Node ${named(node.id)} can only be attached to an instruction or a condition`);
             }
             continue;
         }
         if (node.kind === "trigger" && parents !== 0)
             invalid("The trigger cannot have an incoming edge");
         if (node.kind !== "trigger" && parents !== 1) {
-            invalid(`Node ${node.id} requires exactly one incoming edge`);
+            invalid(`Node ${named(node.id)} requires exactly one incoming edge`);
         }
         if (node.kind === "output" && children.length !== 0)
-            invalid(`Output ${node.id} must be terminal`);
+            invalid(`Output ${named(node.id)} must be terminal`);
         if (node.kind === "condition") {
             if (children.length < 2)
-                invalid(`Node ${node.id} requires at least two branches`);
+                invalid(`Node ${named(node.id)} requires at least two branches`);
             const handles = new Set(children.map((edge) => edge.sourceHandle));
             if (handles.has(null) || handles.size !== children.length) {
-                invalid(`Node ${node.id} requires unique branch handles`);
+                invalid(`Node ${named(node.id)} requires unique branch handles`);
             }
         }
         else if (node.kind !== "output") {
             if (children.length !== 1)
-                invalid(`Node ${node.id} requires exactly one outgoing edge`);
+                invalid(`Node ${named(node.id)} requires exactly one outgoing edge`);
             if (children[0]?.sourceHandle !== null)
-                invalid(`Node ${node.id} cannot define a branch handle`);
+                invalid(`Node ${named(node.id)} cannot define a branch handle`);
         }
     }
     const visited = new Set();
@@ -369,6 +404,67 @@ export function createFlows(deps) {
             throw new IntelError(403, "flow_run_forbidden", "Flow run permission is required");
         }
     }
+    // Managing a flow's sharing is `share` on the flow — held directly, passed down by a folder above
+    // it, or held by owning it. Asked before any grant row is read or written, so a refusal leaves no
+    // trace and tells the caller nothing about what grants exist.
+    async function requireShareable(actor, flowId) {
+        const flow = await requireFlow(actor, flowId);
+        if (!(await deps.repository.can(actor, flow.id, "share"))) {
+            throw new IntelError(403, "flow_forbidden", "Sharing of this flow cannot be managed");
+        }
+        return flow;
+    }
+    /**
+     * What this grant does NOT reach, described to whoever just made it (ADR-0004 §4).
+     *
+     * Two halves, and the second is the one a folder grant never needed. A grant on a folder covered
+     * every flow beneath it, so the sub-flows were covered with it; a grant on ONE flow stops at that
+     * flow, and the flows it calls are then a separate grant somebody has to make.
+     *
+     * ⚠️ It is a warning and not a refusal, for the reason the node side gives: blocking would force
+     * everyone whose flow reads a central policy document to duplicate it. What makes the warning
+     * enough — and what makes this whole feature possible at all — is that `validate` answers the same
+     * question later, for the person about to run, at the moment they run (#530).
+     *
+     * ⚠️ Titles only where the SHARER may see them. Whoever holds `share` on one flow must not learn
+     * the titles of documents or flows they cannot reach themselves, so the rest is a number. A
+     * warning must not become a way of reading the tree (ADR-0004 §3, #17's review).
+     */
+    async function withShareWarnings(actor, flow, grant, principal) {
+        const grantee = asPrincipalActor(principal);
+        // What the published version does is what a grantee will run. A flow with nothing published
+        // has nothing to warn about yet, and the draft is not what `execute` would reach.
+        const versionId = flow.publishedVersionId;
+        const version = versionId ? await deps.repository.getVersion(versionId) : null;
+        if (!version) {
+            return { grant, unreadable: empty(), unrunnable: empty() };
+        }
+        const unreadable = empty();
+        // Deduplicated: a document two steps both name is one thing the grantee cannot read, not two.
+        for (const nodeId of [...new Set(graphReferences(version.graph).nodes)]) {
+            if (await deps.visibleNodes(grantee, nodeId))
+                continue;
+            const node = await deps.visibleNodes(actor, nodeId);
+            if (node)
+                unreadable.titles.push(node.title);
+            else
+                unreadable.hidden += 1;
+        }
+        const unrunnable = empty();
+        for (const calleeId of calleeIds(version.graph)) {
+            if (await deps.repository.can(grantee, calleeId, "execute"))
+                continue;
+            const callee = await deps.repository.getVisible(actor, calleeId);
+            if (callee)
+                unrunnable.titles.push(callee.title);
+            else
+                unrunnable.hidden += 1;
+        }
+        return { grant, unreadable, unrunnable };
+    }
+    function empty() {
+        return { titles: [], hidden: 0 };
+    }
     async function requireEdit(actor, flowId) {
         const flow = await requireFlow(actor, flowId);
         if (!(await deps.repository.can(actor, flowId, "write"))) {
@@ -1105,6 +1201,7 @@ export function createFlows(deps) {
                     flowId: flow.id,
                     versionId: null,
                     nodes: [],
+                    invalidNodes: [],
                     hiddenNodes: 0,
                     servers: [],
                 };
@@ -1112,19 +1209,101 @@ export function createFlows(deps) {
             const version = await requireVersion(versionId, flow.id);
             const referenced = graphReferences(version.graph);
             // ⚠️ The same lookup a tree link passes through, not a second rule written for a list.
-            // What it hands back is named; the difference between what was asked for and what came back
-            // is a number, because a title is exactly what someone without access may not learn (#17,
-            // #19). Tool names are not filtered: they come from a graph this actor may already read, and
-            // whether the portal offers them is a question only their own token can answer.
+            // What it hands back is named; a title is exactly what someone without access may not learn
+            // (#17, #19). Tool names are not filtered: they come from a graph this actor may already
+            // read, and whether the portal offers them is a question only their own token can answer.
             const reachable = await reachableNodes(actor, referenced.nodes);
+            const named = new Set(reachable.map((reference) => reference.id));
+            const unreachable = referenced.nodes.filter((resourceId) => !named.has(resourceId));
+            // ⚠️ What is left over used to be ONE number, and the panel read it out as "you cannot see
+            // it" — a sentence about a permission, in front of a link that names nothing at all (#509).
+            // The two suggest opposite actions and only one of them helps: with a permission one asks for
+            // access, with a dead reference the step has to be replaced before the flow can run.
+            //
+            // ⚠️ The second question is asked ONLY about what the visibility door already refused, and it
+            // is asked without an actor because its answer does not depend on one. That is the narrowest
+            // shape this distinction can have — the alternative, a lookup that is kinder than the door it
+            // describes, is what #17 and #19 were sent back for. It is still a disclosure and it is a
+            // deliberate one (#492): for an id the caller wrote into this graph themselves, they learn
+            // whether the tree still holds a row for it.
+            const alive = new Set(await deps.repository.existingNodes(unreachable));
+            const invalidNodes = unreachable.filter((resourceId) => !alive.has(resourceId));
             return {
                 flowId: flow.id,
                 versionId: version.id,
                 nodes: reachable,
-                hiddenNodes: referenced.nodes.length - reachable.length,
+                invalidNodes,
+                hiddenNodes: unreachable.length - invalidNodes.length,
                 servers: referenced.servers,
             };
         },
+        async listGrants(actor, flowId) {
+            const flow = await requireShareable(actor, flowId);
+            return {
+                resourceId: flow.id,
+                applicableVerbs: flowVerbs,
+                items: await deps.repository.listFlowGrants(flow.id),
+            };
+        },
+        async listEffectiveAccess(actor, flowId) {
+            const flow = await requireShareable(actor, flowId);
+            const effective = await deps.repository.listEffectiveFlowAccess(flow.id);
+            return { resourceId: flow.id, ...effective };
+        },
+        async share(actor, input) {
+            const flow = await requireShareable(actor, input.flowId);
+            const replayedId = await deps.repository.findIdempotent(actor.id, "flows.share", input.idempotencyKey);
+            const principal = input.principal.type === "email"
+                ? { type: "email", email: input.principal.email.toLowerCase() }
+                : input.principal;
+            if (replayedId) {
+                const replayed = (await deps.repository.listFlowGrants(flow.id)).find((grant) => grant.id === replayedId);
+                // A replay describes the same access the first attempt did, so the warning is asked again
+                // rather than remembered: what the grantee can reach may have changed since.
+                if (replayed)
+                    return await withShareWarnings(actor, flow, replayed, replayed.principal);
+            }
+            // ⚠️ The same rule as on a node grant, in the same place and for the same two reasons (#442):
+            // in front of `setFlowGrant` so nothing that could never work is written, behind the replay so
+            // a retry with the same key still answers with the grant its first attempt made. The long
+            // form of the argument stands at the node grant in `nodes.ts`.
+            requireFutureExpiry(input.expiresAt, deps.now());
+            const timestamp = deps.now().toISOString();
+            const grant = await deps.repository.setFlowGrant({
+                grant: {
+                    id: deps.id(),
+                    resourceId: flow.id,
+                    principal,
+                    verb: input.verb,
+                    expiresAt: input.expiresAt,
+                    createdBy: actor.id,
+                    createdAt: timestamp,
+                },
+                flowId: flow.id,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            // ⚠️ After the grant is written, never before. The answer describes the access now in force,
+            // and a warning computed a moment earlier would still list what this very grant just opened.
+            return await withShareWarnings(actor, flow, grant, principal);
+        },
+        async revokeGrant(actor, input) {
+            const flow = await requireShareable(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotentFlowRevocation(actor.id, input.idempotencyKey);
+            if (replayed !== null)
+                return { revoked: replayed };
+            return {
+                revoked: await deps.repository.revokeFlowGrant({
+                    flowId: flow.id,
+                    grantId: input.grantId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
         async create(actor, input) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.create", input.idempotencyKey);
             if (replayed)

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

@@ -1,7 +1,7 @@
 import type { ArchiveFlowInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowValidation, FlowVersion, FlowVersionList, FlowVersionSummary, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput } from "@anchrd/intel-contract/flow";
 import type { CancelFlowRunInput, CompleteFlowRunStepInput, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, ListFlowRunsInput, StartFlowRunInput } from "@anchrd/intel-contract/flow-run";
 import type { Node } from "@anchrd/intel-contract/node";
-import type { ResourceVerb } from "@anchrd/intel-contract/share";
+import type { ResourceAccessList, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeFlowGrantInput, RevokeGrantResult, ShareFlowInput, ShareResult } from "@anchrd/intel-contract/share";
 export type FlowPrincipal = Pick<FlowActor, "id" | "email" | "isAdmin">;
 export type FlowCallReach = "subtree" | "library" | "out-of-reach";
 export interface FlowRunChainEntry {
@@ -42,8 +42,8 @@ export interface FlowActor {
     canRun: boolean;
     isAdmin?: boolean;
 }
-export type FlowVerb = Extract<ResourceVerb, "read" | "write" | "execute">;
-export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.cancel" | "flows.unpublish";
+export type FlowVerb = ResourceVerb;
+export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.cancel" | "flows.unpublish" | "flows.share" | "flows.revoke";
 export interface BoundedLevel<T> {
     items: T[];
     total: number;
@@ -53,6 +53,27 @@ export interface FlowRepository {
     listVisibleBounded(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<Flow>>;
     getVisible(actor: FlowActor, flowId: string): Promise<Flow | null>;
     can(actor: FlowActor, flowId: string, verb: FlowVerb): Promise<boolean>;
+    listFlowGrants(flowId: string): Promise<ResourceGrant[]>;
+    listEffectiveFlowAccess(flowId: string): Promise<{
+        ownerIds: string[];
+        items: ResourceGrant[];
+    }>;
+    setFlowGrant(input: {
+        grant: ResourceGrant;
+        flowId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeFlowGrant(input: {
+        flowId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    findIdempotentFlowRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
     getCallable(actor: FlowActor, flowId: string): Promise<Flow | null>;
     listCallable(actor: FlowActor, flowIds: string[]): Promise<Flow[]>;
     callReach(callerFolderId: string | null, calleeFolderId: string | null): Promise<FlowCallReach>;
@@ -61,6 +82,21 @@ export interface FlowRepository {
         hidden: number;
     }>;
     nodeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
+    /**
+     * Which of these ids still have a row in the tree at all — archived or not, for anybody (#509).
+     *
+     * ⚠️ It takes NO actor, and that is the honest shape rather than an oversight: the answer does
+     * not depend on who is asking, so an `actor` parameter would suggest a narrowing that is not
+     * there. Its one caller has already asked `visibleNodes` and only reaches this for the ids that
+     * came back empty, so what it adds is a single bit about ids the caller sent us out of a graph
+     * they may already read.
+     *
+     * ⚠️ An ARCHIVED node counts as existing. Archiving is reversible — the row is still there and a
+     * restore brings the reference back — so calling it invalid would tell an author to replace a
+     * step that is about to work again. Only a purge takes the row (`DELETE FROM nodes`, #457), and
+     * only that is what "there is nothing here any more" means.
+     */
+    existingNodes(nodeIds: string[]): Promise<string[]>;
     publishedCallees(flowId: string): Promise<{
         title: string;
         calleeIds: string[];
@@ -207,6 +243,12 @@ export interface FlowDeps {
      * requirements list names it; and every tree link of every run is authorized by it, nested
      * calls included (ADR-0004 §4). A second lookup beside it is how a drawing or a message ends up
      * kinder than the door it describes — which is what #17 and #19 were sent back for.
+     *
+     * ⚠️ `existingNodes` on the repository is the ONE thing asked beside it, and it is the exception
+     * that shows the rule rather than a hole in it: it runs only on ids this door already refused, it
+     * takes no actor, and it can only ever make the answer HARSHER — "this names nothing" instead of
+     * "you cannot see it". Nothing about a node it does hold reaches the caller, so no drawing and no
+     * message becomes kinder. Adding a third would need the same three properties (#492, #509).
      */
     visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
     toolSurfaceFingerprint(actor: FlowActor, server: string, allow: string[] | null): Promise<string | null>;
@@ -228,6 +270,10 @@ export interface FlowService {
     validate(actor: FlowActor, flowId: string): Promise<FlowValidation>;
     relationGraph(actor: FlowActor, input: RelationGraphInput): Promise<RelationGraph>;
     listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
+    listGrants(actor: FlowActor, flowId: string): Promise<ResourceGrantList>;
+    listEffectiveAccess(actor: FlowActor, flowId: string): Promise<ResourceAccessList>;
+    share(actor: FlowActor, input: ShareFlowInput): Promise<ShareResult>;
+    revokeGrant(actor: FlowActor, input: RevokeFlowGrantInput): Promise<RevokeGrantResult>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
     update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
     archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;

package/dist/http/http.js

@@ -1,7 +1,7 @@
 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, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
-import { RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
+import { RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, 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";
 import { Hono } from "hono";
@@ -470,9 +470,33 @@ export function createHttp(deps) {
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
         return context.json(await deps.flows.listRequirements(asFlowActor(auth), input.flowId));
     });
-    // A flow has no grant route of its own. It is shared through the folder it is filed in, under
-    // /nodes/:nodeId/grants — one place answers the question for the documents and the flows in
-    // that folder alike (ADR-0004 §2).
+    // 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));