@anchrd/intel-api 0.22.0 → 0.24.0

package/README.md

@@ -303,8 +303,10 @@ the titles of the folders above it. Nobody has to be sent a link.
 
 ### Three things about grants that surprise people
 
-- **A flow is not a node.** It carries no grants of its own; it inherits those of the folder it
-  lives in. Move a flow and you have changed who can reach it.
+- **A flow is not a node, and is reached by two things at once.** The folder it is filed in passes
+  its grants down, and since #530 a grant may sit on the flow itself; they add up. Move a flow and
+  you have changed the first half of that. A grant on one flow does not reach the flows it calls —
+  the answer names them, and `flow_validate` tells the person about to run what is still missing.
 - **`organization` + `execute` on a folder makes that folder a library**: flows from anywhere in the
   tree may then call into it. The share dialog warns before the click, because the way back is
   narrow — revoking is refused with `409 folder_execute_in_use` for as long as one of those callers

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

@@ -1,7 +1,7 @@
 import { Flow, FlowGraph, FlowVersion, } from "@anchrd/intel-contract/flow";
 import { FlowRun } from "@anchrd/intel-contract/flow-run";
 import { calleeIds, treeLinkKinds } from "../../flows/flows.js";
-import { flowCallable, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { flowCallable, flowCallableBindings, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, grantColumns, grantInForce, mapGrant, principalColumns, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const flowColumnNames = [
     "id",
     "parent_id",
@@ -71,9 +71,9 @@ function mapVersion(row) {
 // it was started. Everything else is the folder the flow is filed in, read through `flowInSubtree`,
 // the very predicate the flow list itself uses.
 //
-// It expects `flow_runs run` joined to `flows flow`, and its bindings follow the CTE's.
+// It expects `flow_runs run` joined to `flows flow`, and its bindings follow the CTE's. The bindings
+// live in the factory below because `flowInSubtree` now needs the moment expiry is measured against.
 const runVisible = `(run.initiated_by = ? OR ${flowInSubtree})`;
-const runVisibleBindings = (actor) => [actor.id, ...flowInSubtreeBindings(actor)];
 function mapStep(row) {
     return {
         runId: row.run_id,
@@ -106,11 +106,17 @@ function mapRun(row) {
 // statement may carry, and the lists here are as long as a graph, a call chain or a drawn level —
 // so an `IN (?, ?, …)` built from the input would be a limit waiting to be hit by real data (#30).
 const idList = "(SELECT value FROM json_each(?))";
+const flowGrantColumns = grantColumns("flow_id");
 export function createFlowRepository(deps) {
-    // A flow holds no grant of its own any more (ADR-0004 §2). What reaches it is the folder it is
-    // filed in, read through the same walk the tree uses, so the two can never drift apart. The CTE
-    // stands in front of the statement, so its bindings come before every other one.
+    // The folders this actor may open, read through the same walk the tree uses, so the two can never
+    // drift apart. The CTE stands in front of the statement, so its bindings come before every other
+    // one.
     const readableBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
+    // The other half of the same question since #530: the folders this actor reads come from the walk
+    // above, the flows handed to them directly come from `flow_grants`. Always `read` here, because
+    // every statement these two appear in together is seeded with `read`.
+    const inSubtreeBindings = (actor) => flowInSubtreeBindings(actor, "read", deps.now().toISOString());
+    const runVisibleBindings = (actor) => [actor.id, ...inSubtreeBindings(actor)];
     // An absent `parentId` asks for every visible flow; `null` asks for the root of the shared tree.
     // `IS ?` would collapse the two, so the two cases are separate SQL rather than one binding that
     // silently means both.
@@ -152,14 +158,14 @@ export function createFlowRepository(deps) {
             SELECT ${flowColumns} FROM flows flow
             WHERE ${flowInSubtree} AND flow.archived_at IS NOT NULL
             ORDER BY flow.archived_at DESC, lower(flow.title), flow.id`)
-                    .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor))
+                    .bind(...readableBindings(actor), ...inSubtreeBindings(actor))
                     .all();
                 return (result.results ?? []).map(mapFlow);
             }
             const scope = scopeOf(input.parentId);
             const result = await deps.db
                 .prepare(visibleFlows(scope.clause, false, input.includeArchived === true))
-                .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings)
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings)
                 .all();
             return (result.results ?? []).map(mapFlow);
         },
@@ -167,7 +173,7 @@ export function createFlowRepository(deps) {
             const scope = scopeOf(folderId);
             const result = await deps.db
                 .prepare(visibleFlows(scope.clause, true))
-                .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings, limit)
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings, limit)
                 .all();
             const rows = result.results ?? [];
             return { items: rows.map(mapFlow), total: rows[0]?.total ?? 0 };
@@ -177,10 +183,175 @@ export function createFlowRepository(deps) {
                 .prepare(`${subtreeCte}
           SELECT ${flowColumns} FROM flows flow
           WHERE flow.id = ? AND ${flowInSubtree}`)
-                .bind(...readableBindings(actor), flowId, ...flowInSubtreeBindings(actor))
+                .bind(...readableBindings(actor), flowId, ...inSubtreeBindings(actor))
                 .first();
             return row ? mapFlow(row) : null;
         },
+        async listFlowGrants(flowId) {
+            const result = await deps.db
+                .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+          WHERE flow_id = ?
+          ORDER BY principal_type, principal_id, verb`)
+                .bind(flowId)
+                .all();
+            return (result.results ?? []).map(mapGrant);
+        },
+        // ⚠️ Owners and grants out of ONE statement, hence one D1 snapshot, for the reason the node side
+        // gives: two parallel SELECTs are not atomic, and a grant written between their snapshots
+        // produces a principal list that never existed as a whole.
+        //
+        // ⚠️ The grants come from BOTH tables. Reading only `flow_grants` here would draw a flow as
+        // though the folder above it granted nothing — which is the everyday case, not the exception.
+        async listEffectiveFlowAccess(flowId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT folder.id, folder.parent_id, folder.owner_id
+            FROM nodes folder
+            JOIN flows flow ON flow.parent_id = folder.id
+            WHERE flow.id = ?
+            UNION
+            SELECT parent.id, parent.parent_id, parent.owner_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT
+            (SELECT json_group_array(owner_id) FROM (
+               SELECT DISTINCT owner_id FROM (
+                 SELECT owner_id FROM flows WHERE id = ?
+                 UNION
+                 SELECT owner_id FROM ancestors
+               ) ORDER BY owner_id
+             )) AS owner_ids_json,
+            (SELECT json_group_array(json_object(
+               'id', id, 'resource_id', resource_id, 'principal_type', principal_type,
+               'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
+               'created_by', created_by, 'created_at', created_at
+             ))
+             FROM (
+               SELECT grant_row.id, grant_row.flow_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM flow_grants grant_row
+               WHERE grant_row.flow_id = ?
+                 AND ${grantInForce}
+               UNION ALL
+               SELECT grant_row.id, grant_row.node_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE ${grantInForce}
+               ORDER BY principal_type, principal_id, verb
+             )) AS grants_json`)
+                .bind(flowId, flowId, flowId, deps.now().toISOString(), deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                items: JSON.parse(row?.grants_json ?? "[]").map(mapGrant),
+            };
+        },
+        async setFlowGrant(input) {
+            const grant = input.grant;
+            const { type: principalType, id: principalId } = principalColumns(grant.principal);
+            try {
+                await deps.db.batch([
+                    deps.db
+                        // The verb is part of the key, so re-granting the same verb only refreshes its expiry
+                        // and never turns one verb into another.
+                        .prepare(`INSERT INTO flow_grants (
+              id, flow_id, principal_type, principal_id, verb,
+              expires_at, created_by, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (flow_id, principal_type, principal_id, verb)
+            DO UPDATE SET expires_at = excluded.expires_at`)
+                        .bind(grant.id, input.flowId, principalType, principalId, grant.verb, grant.expiresAt, grant.createdBy, grant.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.share', ?, id, ? FROM flow_grants
+              WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, input.flowId, principalType, principalId, grant.verb),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'flows.share', 'flow', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
+                ]);
+                const stored = await deps.db
+                    .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+            WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                    .bind(input.flowId, principalType, principalId, grant.verb)
+                    .first();
+                if (!stored)
+                    throw new Error("Flow grant disappeared after upsert");
+                return mapGrant(stored);
+            }
+            catch (error) {
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'flows.share' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (replayed) {
+                    const row = await deps.db
+                        .prepare(`SELECT ${flowGrantColumns} FROM flow_grants WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first();
+                    if (row)
+                        return mapGrant(row);
+                }
+                throw error;
+            }
+        },
+        // ⚠️ Whether the row was there is decided BEFORE it is deleted and remembered in the
+        // idempotency key's own value, because afterwards nothing can tell "I removed it" from "it was
+        // never here" — and a replay that answered `true` to the second would claim a deletion that did
+        // not happen. The `1:`/`0:` prefix is the node side's device, and it is the same device here.
+        async revokeFlowGrant(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.revoke', ?,
+              (CASE WHEN EXISTS (
+                SELECT 1 FROM flow_grants WHERE id = ? AND flow_id = ?
+              ) THEN '1:' ELSE '0:' END) || ?, ?`)
+                        .bind(input.actorId, input.idempotencyKey, input.grantId, input.flowId, input.grantId, input.occurredAt),
+                    deps.db
+                        .prepare("DELETE FROM flow_grants WHERE id = ? AND flow_id = ?")
+                        .bind(input.grantId, input.flowId),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.revoke', 'flow', ?,
+              json_object(
+                'grantId', ?,
+                'revoked', json(CASE WHEN substr(resource_id, 1, 2) = '1:' THEN 'true' ELSE 'false' END)
+              ), ?
+              FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                        .bind(input.auditId, input.actorId, input.flowId, input.grantId, input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey);
+                if (replayed === null)
+                    throw error;
+                return replayed;
+            }
+            return ((await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey)) ?? false);
+        },
+        async findIdempotentFlowRevocation(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            return row.resource_id.startsWith("1:");
+        },
         async can(actor, flowId, verb) {
             const row = await deps.db
                 .prepare(flowVerbQuery)
@@ -202,7 +373,7 @@ export function createFlowRepository(deps) {
           SELECT ${flowColumns} FROM flows flow
           WHERE flow.id IN ${idList} AND ${flowCallable}
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", occurredAt), ...subtreeBindings(actor, "execute", occurredAt), JSON.stringify(flowIds), ...flowInSubtreeBindings(actor))
+                .bind(...subtreeBindings(actor, "read", occurredAt), ...subtreeBindings(actor, "execute", occurredAt), JSON.stringify(flowIds), ...flowCallableBindings(actor, occurredAt))
                 .all();
             return (result.results ?? []).map(mapFlow);
         },
@@ -233,7 +404,7 @@ export function createFlowRepository(deps) {
               JOIN ancestors ON ancestors.id = grant_row.node_id
               WHERE grant_row.principal_type = 'organization'
                 AND grant_row.verb = 'execute'
-                AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+                AND ${grantInForce}
             ) AS library`)
                 .bind(calleeFolderId, callerFolderId, deps.now().toISOString())
                 .first();
@@ -267,7 +438,7 @@ export function createFlowRepository(deps) {
             AND callee.parent_id IN (SELECT id FROM scope)
             AND (flow.parent_id IS NULL OR flow.parent_id NOT IN (SELECT id FROM scope))
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...flowInSubtreeBindings(actor))
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
                 .all();
             const rows = result.results ?? [];
             return {
@@ -291,7 +462,7 @@ export function createFlowRepository(deps) {
             AND flow.archived_at IS NULL
             AND flow.id <> ?
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), flowId, flowId)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), flowId, flowId)
                 .all();
             const rows = result.results ?? [];
             return {
@@ -315,7 +486,7 @@ export function createFlowRepository(deps) {
             AND json_extract(node.value, '$.configuration.resourceId') = ?
             AND flow.archived_at IS NULL
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), nodeId)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), nodeId)
                 .all();
             const rows = result.results ?? [];
             return {
@@ -381,6 +552,13 @@ export function createFlowRepository(deps) {
                 deps.db
                     .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${aliveFlow}`)
                     .bind(input.flowId, input.flowId),
+                // The grants that sat on the flow itself (#530). They point at `flows(id)`, so they have to
+                // go before the row does — and they carry the same guard as everything above for the same
+                // reason: a batch whose last statement matches nothing still commits, and a restore in
+                // between would leave a living flow stripped of every grant somebody set on it.
+                deps.db
+                    .prepare(`DELETE FROM flow_grants WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
                 // ⚠️ LAST, and still guarded — a restore between the service's check and this statement
                 // would otherwise cost a living flow.
                 deps.db
@@ -425,7 +603,7 @@ export function createFlowRepository(deps) {
           FROM referencing
           WHERE resource_id IS NOT NULL
           ORDER BY resource_id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...flowInSubtreeBindings(actor))
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
                 .all();
             return (result.results ?? []).map((row) => row.resource_id);
         },

package/dist/adapters/db/db-grants.d.ts

@@ -1,9 +1,46 @@
-import type { ResourceVerb } from "@anchrd/intel-contract/share";
+import type { ResourceGrant, ResourceVerb } from "@anchrd/intel-contract/share";
 export interface GrantActor {
     id: string;
     email: string;
     isAdmin?: boolean;
 }
+/**
+ * A grant row as every reader of one wants it: the subject column already aliased, so the same row
+ * shape comes back from `node_grants` and from `flow_grants`.
+ *
+ * ⚠️ The alias is what lets `mapGrant` stay one function. Two mappers would each carry the same
+ * `principal_type` switch, and the day a fourth principal shape arrives one of them gets it.
+ */
+export interface GrantRow {
+    id: string;
+    resource_id: string;
+    principal_type: "user" | "email" | "organization";
+    principal_id: string;
+    verb: ResourceVerb;
+    expires_at: string | null;
+    created_by: string;
+    created_at: string;
+}
+export declare const grantColumns: (subjectColumn: string) => string;
+export declare function mapGrant(row: GrantRow): ResourceGrant;
+export declare function principalColumns(principal: ResourceGrant["principal"]): {
+    type: ResourceGrant["principal"]["type"];
+    id: string;
+};
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/api/src` must find this line and nothing else.
+ */
+export declare const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
 export declare const subtreeCte: string;
 export declare function subtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
@@ -27,9 +64,14 @@ export declare const readableOrRunnableCte: string;
  * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
  * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
  * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
- * time. Its bindings follow the two CTEs' and are `flowInSubtreeBindings(actor)`.
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
  */
-export declare const flowCallable = "(\n  ? = 1\n  OR flow.owner_id = ?\n  OR flow.parent_id IN (SELECT id FROM readable)\n  OR flow.parent_id IN (SELECT id FROM runnable)\n)";
+export declare const flowCallable: string;
+export declare function flowCallableBindings(actor: GrantActor, now: string): unknown[];
 /**
  * The point check for one node: the node itself and every ancestor above it. Cheaper than
  * the subtree walk and the same answer, because a grant reaches down and never sideways.
@@ -43,16 +85,26 @@ export declare const flowCallable = "(\n  ? = 1\n  OR flow.owner_id = ?\n  OR fl
 export declare const nodeVerbQuery: string;
 export declare function nodeVerbBindings(nodeId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
- * The same question for a flow. A flow carries no grant of its own any more: what reaches it is the
- * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a node's
- * owner keeps theirs — otherwise a flow at the root of the tree would be unreachable by the person
- * who created it. `UNION` for the same reason as above.
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
  */
 export declare const flowVerbQuery: string;
 export declare function flowVerbBindings(flowId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
  * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
  * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
  */
-export declare const flowInSubtree = "(? = 1 OR flow.owner_id = ? OR flow.parent_id IN (SELECT id FROM allowed))";
-export declare function flowInSubtreeBindings(actor: GrantActor): unknown[];
+export declare const flowInSubtree: string;
+export declare function flowInSubtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];

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

@@ -1,17 +1,82 @@
+export const grantColumns = (subjectColumn) => `id, ${subjectColumn} AS resource_id, principal_type, principal_id, verb, expires_at,
+  created_by, created_at`;
+export function mapGrant(row) {
+    let principal;
+    switch (row.principal_type) {
+        case "user":
+            principal = { type: "user", id: row.principal_id };
+            break;
+        case "email":
+            principal = { type: "email", email: row.principal_id };
+            break;
+        case "organization":
+            principal = { type: "organization" };
+            break;
+        default:
+            throw new Error("Unsupported grant principal type");
+    }
+    return {
+        id: row.id,
+        resourceId: row.resource_id,
+        principal,
+        verb: row.verb,
+        expiresAt: row.expires_at,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    };
+}
+// How a principal is written into the subject columns of both grant tables. An organization is the
+// literal `*` every reader above matches on; an email is folded to lower case on the way in so the
+// comparison there has one shape to worry about.
+export function principalColumns(principal) {
+    if (principal.type === "user")
+        return { type: "user", id: principal.id };
+    if (principal.type === "email")
+        return { type: "email", id: principal.email.toLowerCase() };
+    return { type: "organization", id: "*" };
+}
 const principalMatch = `(
   (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
   OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
   OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
 )`;
-function grantExists(nodeColumn) {
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/api/src` must find this line and nothing else.
+ */
+export const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
+/**
+ * One grant row that is in force, asked of one table.
+ *
+ * ⚠️ The table is a parameter and the rest is not, which is the whole reason #530 could give a flow
+ * its own grants without a second set of doors. `flow_grants` and `node_grants` differ in their
+ * subject column and in nothing else — same principal shapes, same verbs, same expiry — so a
+ * question asked of one is asked of the other by the same string. A hand-written copy for flows is
+ * how one of the two would eventually stop honouring `expires_at`.
+ */
+function grantExists(table, subjectColumn, targetColumn) {
     return `EXISTS (
-    SELECT 1 FROM node_grants grant_row
-    WHERE grant_row.node_id = ${nodeColumn}
+    SELECT 1 FROM ${table} grant_row
+    WHERE grant_row.${subjectColumn} = ${targetColumn}
       AND ${principalMatch}
       AND grant_row.verb = ?
-      AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+      AND ${grantInForce}
   )`;
 }
+const nodeGrantExists = (nodeColumn) => grantExists("node_grants", "node_id", nodeColumn);
+// A grant that sits on the flow itself (#530), beside whatever its folder already passes down. It
+// adds to the folder's reach and never replaces it, exactly as a grant on a document adds to its
+// folder's — the two are OR-ed everywhere this appears.
+const flowGrantExists = (flowColumn) => grantExists("flow_grants", "flow_id", flowColumn);
 // Bindings for one `grantExists`: principal (twice), verb, and the moment expiry is measured
 // against. Callers concatenate these in SQL order; the helpers below say which order that is.
 function grantBindings(actor, verb, now) {
@@ -29,7 +94,7 @@ function subtreeWalk(name) {
     FROM nodes seed
     WHERE ? = 1
        OR seed.owner_id = ?
-       OR ${grantExists("seed.id")}
+       OR ${nodeGrantExists("seed.id")}
     UNION
     SELECT child.id, child.parent_id
     FROM nodes child
@@ -70,14 +135,28 @@ export const readableOrRunnableCte = `WITH RECURSIVE ${subtreeWalk("readable")},
  * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
  * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
  * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
- * time. Its bindings follow the two CTEs' and are `flowInSubtreeBindings(actor)`.
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
  */
 export const flowCallable = `(
   ? = 1
   OR flow.owner_id = ?
   OR flow.parent_id IN (SELECT id FROM readable)
   OR flow.parent_id IN (SELECT id FROM runnable)
+  OR ${flowGrantExists("flow.id")}
+  OR ${flowGrantExists("flow.id")}
 )`;
+export function flowCallableBindings(actor, now) {
+    return [
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, "read", now),
+        ...grantBindings(actor, "execute", now),
+    ];
+}
 /**
  * The point check for one node: the node itself and every ancestor above it. Cheaper than
  * the subtree walk and the same answer, because a grant reaches down and never sideways.
@@ -99,16 +178,21 @@ export const nodeVerbQuery = `WITH RECURSIVE ancestors(id, parent_id, owner_id)
   FROM ancestors
   WHERE ? = 1
      OR owner_id = ?
-     OR ${grantExists("ancestors.id")}
+     OR ${nodeGrantExists("ancestors.id")}
   LIMIT 1`;
 export function nodeVerbBindings(nodeId, actor, verb, now) {
     return [nodeId, actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }
 /**
- * The same question for a flow. A flow carries no grant of its own any more: what reaches it is the
- * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a node's
- * owner keeps theirs — otherwise a flow at the root of the tree would be unreachable by the person
- * who created it. `UNION` for the same reason as above.
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
  */
 export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
     SELECT folder.id, folder.parent_id
@@ -126,17 +210,35 @@ export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
     AND (
       ? = 1
       OR flow.owner_id = ?
-      OR EXISTS (SELECT 1 FROM ancestors WHERE ${grantExists("ancestors.id")})
+      OR ${flowGrantExists("flow.id")}
+      OR EXISTS (SELECT 1 FROM ancestors WHERE ${nodeGrantExists("ancestors.id")})
     )
   LIMIT 1`;
 export function flowVerbBindings(flowId, actor, verb, now) {
-    return [flowId, flowId, actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
+    return [
+        flowId,
+        flowId,
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, verb, now),
+        ...grantBindings(actor, verb, now),
+    ];
 }
 /**
  * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
  * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
  */
-export const flowInSubtree = `(? = 1 OR flow.owner_id = ? OR flow.parent_id IN (SELECT id FROM allowed))`;
-export function flowInSubtreeBindings(actor) {
-    return [actor.isAdmin ? 1 : 0, actor.id];
+export const flowInSubtree = `(
+  ? = 1
+  OR flow.owner_id = ?
+  OR flow.parent_id IN (SELECT id FROM allowed)
+  OR ${flowGrantExists("flow.id")}
+)`;
+export function flowInSubtreeBindings(actor, verb, now) {
+    return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }

package/dist/adapters/db/db.js

@@ -1,8 +1,7 @@
-import { descendantsCte, nodeVerbBindings, nodeVerbQuery, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { descendantsCte, grantColumns as grantColumnsFor, grantInForce, mapGrant, nodeVerbBindings, nodeVerbQuery, principalColumns, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const versionColumns = `id, node_id, sequence, content_key, media_type, content_hash,
   size, segment, created_by, created_at`;
-const grantColumns = `id, node_id, principal_type, principal_id, verb, expires_at,
-  created_by, created_at`;
+const grantColumns = grantColumnsFor("node_id");
 const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
   link.origin, link.label, link.created_by, link.created_at`;
 // The first row of each node, in the order they arrive. A chunked kind — one whose index holds
@@ -47,31 +46,6 @@ function mapVersion(row) {
         createdAt: row.created_at,
     };
 }
-function mapGrant(row) {
-    let principal;
-    switch (row.principal_type) {
-        case "user":
-            principal = { type: "user", id: row.principal_id };
-            break;
-        case "email":
-            principal = { type: "email", email: row.principal_id };
-            break;
-        case "organization":
-            principal = { type: "organization" };
-            break;
-        default:
-            throw new Error("Unsupported node grant principal type");
-    }
-    return {
-        id: row.id,
-        resourceId: row.node_id,
-        principal,
-        verb: row.verb,
-        expiresAt: row.expires_at,
-        createdBy: row.created_by,
-        createdAt: row.created_at,
-    };
-}
 function mapLink(row) {
     return {
         id: row.id,
@@ -1029,7 +1003,7 @@ export function createNodeRepository(deps) {
             (SELECT json_group_array(owner_id)
              FROM (SELECT DISTINCT owner_id FROM ancestors ORDER BY owner_id)) AS owner_ids_json,
             (SELECT json_group_array(json_object(
-               'id', id, 'node_id', node_id, 'principal_type', principal_type,
+               'id', id, 'resource_id', node_id, 'principal_type', principal_type,
                'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
                'created_by', created_by, 'created_at', created_at
              ))
@@ -1039,7 +1013,7 @@ export function createNodeRepository(deps) {
                  grant_row.created_by, grant_row.created_at
                FROM node_grants grant_row
                JOIN ancestors ON ancestors.id = grant_row.node_id
-               WHERE grant_row.expires_at IS NULL OR grant_row.expires_at > ?
+               WHERE ${grantInForce}
                ORDER BY grant_row.principal_type, grant_row.principal_id, grant_row.verb
              )) AS grants_json`)
                 .bind(resourceId, deps.now().toISOString())
@@ -1066,7 +1040,7 @@ export function createNodeRepository(deps) {
           WHERE grant_row.id <> ?
             AND grant_row.principal_type = 'organization'
             AND grant_row.verb = 'execute'
-            AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+            AND ${grantInForce}
           LIMIT 1`)
                 .bind(nodeId, exceptGrantId, deps.now().toISOString())
                 .first();
@@ -1173,12 +1147,7 @@ export function createNodeRepository(deps) {
         },
         async setGrant(input) {
             const grant = input.grant;
-            const principalType = grant.principal.type;
-            const principalId = grant.principal.type === "user"
-                ? grant.principal.id
-                : grant.principal.type === "email"
-                    ? grant.principal.email.toLowerCase()
-                    : "*";
+            const { type: principalType, id: principalId } = principalColumns(grant.principal);
             try {
                 await deps.db.batch([
                     deps.db

package/dist/flows/flows.js

@@ -7,6 +7,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.
@@ -369,6 +390,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"))) {
@@ -1125,6 +1207,68 @@ export function createFlows(deps) {
                 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);
+            }
+            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)
@@ -1310,10 +1454,24 @@ export function createFlows(deps) {
         async previewPublish(actor, input) {
             const flow = await requireEdit(actor, input.flowId);
             const version = await requireVersion(input.versionId, flow.id);
+            // ⚠️ `available` is asked with the VERY call that publishing uses, not with a cheaper one that
+            // answers a similar question. `unavailableServers` only says whether a server reaches
+            // anything; publishing asks whether THIS step's surface is whole — and those differ exactly
+            // where it hurts: a narrowed step whose allowed function disappeared keeps a reachable
+            // server, so the cheap question says "fine" and the confirmation then answers 409. A preview
+            // that promises a freeze the confirmation denies is worse than no preview.
+            const tools = await Promise.all(toolNodes(version.graph).map(async (node) => ({
+                nodeId: node.id,
+                nodeLabel: node.label,
+                server: node.configuration.server,
+                allow: node.configuration.allow,
+                available: (await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow)) !== null,
+            })));
             return {
                 flowId: flow.id,
                 versionId: version.id,
                 calls: await calls(actor, version.graph),
+                tools,
             };
         },
         async publish(actor, input) {

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>;
@@ -228,6 +249,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));

package/dist/mcp/mcp.js

@@ -2,7 +2,7 @@ import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
 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, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
-import { ListGrantsInput, RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
+import { ListFlowGrantsInput, ListGrantsInput, RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, ShareInput, } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -666,8 +666,46 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.listRunSteps(flowActor, input.runId)));
     }
-    // A flow has no share tool of its own. Sharing happens on the folder a flow is filed in, through
-    // node_grant_create, so a narrower grant cannot sit beside the folder grant (ADR-0004 §2).
+    // The flow's own sharing (#530), named by the same grammar as the node tools: domain singular,
+    // the way narrowing left to right, the verb last.
+    if (permits(deps.authorization, "flows", "share")) {
+        server.registerTool("flow_grant_list", {
+            title: "List flow grants",
+            description: "List the grants sitting on one flow. What the folder it is filed in passes down is not listed here.",
+            inputSchema: ListFlowGrantsInput,
+            annotations: {
+                title: "List flow grants",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listGrants(flowActor, input.flowId)));
+        server.registerTool("flow_grant_create", {
+            title: "Grant flow access",
+            description: "Grant access to one flow for a Gate user, verified email, or the organization. The grant reaches this flow alone — not the folder it is filed in, and not the flows it calls; the answer names what it does not cover.",
+            inputSchema: ShareFlowInput,
+            annotations: {
+                title: "Grant flow access",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.share(flowActor, input)));
+        server.registerTool("flow_grant_revoke", {
+            title: "Revoke flow grant",
+            description: "Revoke one grant sitting on a flow by ID.",
+            inputSchema: RevokeFlowGrantInput,
+            annotations: {
+                title: "Revoke flow grant",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.revokeGrant(flowActor, input)));
+    }
     if (permits(deps.authorization, "flows", "create")) {
         server.registerTool("flow_create", {
             title: "Create flow",

package/dist/nodes/nodes.js

@@ -10,6 +10,11 @@ import { documentLinkTargets } from "./document-links/document-links.js";
 function contentKeyFor(nodeId, versionId) {
     return `nodes/${nodeId}/versions/${versionId}`;
 }
+// A node grant covers every flow beneath the node it sits on, so there is never a sub-flow it fails
+// to reach and this half of the warning is empty here by construction (#530). Written out rather
+// than left to the schema's default: nothing parses a service's answer on the way out, so a default
+// would arrive at the UI as `undefined`.
+const nothingWithheld = { titles: [], hidden: 0 };
 // A verb that cannot apply to a node is neither offered on it nor accepted for it (ADR-0004 §2).
 // The answer lives here rather than in the screen so HTTP, MCP and the UI cannot disagree about it.
 //
@@ -1016,6 +1021,7 @@ export function createNodes(deps) {
                     return {
                         grant: replayed,
                         unreadable: await unreadableForPrincipal(actor, node.id, replayed.principal),
+                        unrunnable: nothingWithheld,
                     };
                 }
             }
@@ -1037,7 +1043,11 @@ export function createNodes(deps) {
             // ⚠️ After the grant is written, never before. The answer has to describe the access that is
             // now in force — sharing `read` on this folder is exactly what makes the documents inside it
             // readable, and a warning computed a moment earlier would name them all.
-            return { grant, unreadable: await unreadableForPrincipal(actor, node.id, principal) };
+            return {
+                grant,
+                unreadable: await unreadableForPrincipal(actor, node.id, principal),
+                unrunnable: nothingWithheld,
+            };
         },
         async revokeGrant(actor, input) {
             await requireVisible(actor, input.resourceId);

package/migrations/0021_a_flow_carries_its_own_grant.sql

@@ -0,0 +1,44 @@
+-- #530: a flow is shared on its own again, the way a document and a table are.
+--
+-- `0003` moved every per-flow grant onto a folder because ADR-0004 §3 promised something a narrower
+-- grant would have broken: "everything A calls is covered by the same grant — automatically, and
+-- for all time". The word that carried the promise was *automatically*. A grant on the flow alone
+-- does not reach the sub-flow filed beside it, and in 2026-08 the run would simply have stopped at
+-- that step, without anyone having been told beforehand.
+--
+-- Being told beforehand is what has been built since: `flow_validate` gathers everything standing
+-- between one person and one run — missing `execute`, an unreachable sub-flow, an unreachable tool,
+-- an unreadable tree link — and answers it per person and per moment, on all three surfaces. The
+-- promise is therefore not restored here; it is replaced by a question anybody can ask. ADR-0004 §2
+-- carries the dated amendment, D49 the reason.
+--
+-- ⚠️ A table of its own, not a widened `node_grants`. A flow is not a node — that is the one thing
+-- ADR-0004 §1 was most explicit about — and `node_grants.node_id` carries a REFERENCES clause into
+-- `nodes`. Making the column polymorphic would mean dropping that clause, and an ACL table whose
+-- rows can outlive their subject is precisely where a stale row keeps handing out access.
+--
+-- Everything else is deliberately identical to `node_grants`, down to the index shape: the two are
+-- read by one predicate builder (`db-grants.ts`), and a difference here would become a difference
+-- in the questions it can ask.
+CREATE TABLE flow_grants (
+  id TEXT PRIMARY KEY NOT NULL,
+  flow_id TEXT NOT NULL REFERENCES flows(id),
+  principal_type TEXT NOT NULL CHECK (principal_type IN ('user', 'email', 'organization')),
+  principal_id TEXT NOT NULL,
+  verb TEXT NOT NULL CHECK (verb IN ('read', 'write', 'execute', 'share')),
+  expires_at TEXT,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  -- The verb belongs in the key, for the reason `0003` gives: without it one principal holds one
+  -- verb per flow, which is the ladder the four independent verbs exist instead of.
+  UNIQUE (flow_id, principal_type, principal_id, verb)
+);
+
+CREATE INDEX flow_grants_principal_idx ON flow_grants(
+  principal_type,
+  principal_id,
+  verb,
+  expires_at
+);
+
+CREATE INDEX flow_grants_flow_idx ON flow_grants(flow_id, verb);

package/package.json

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