@anchrd/intel-api 0.23.0 → 0.25.0

package/dist/intel/intel.js

@@ -97,7 +97,35 @@ export function createIntel(deps) {
                 return context.redirect("/tools?connectError=portal_sign_in_failed");
             }
         });
-        app.get("/auth/callback", async (context) => await browserAuth.callback(new URL(context.req.url), context.req.raw.headers));
+        // The other end of the same walk: `/auth/connect` starts it, `/auth/callback` finishes it, and
+        // a reader who lands in a white JSON page does not distinguish which of the two put them there
+        // (#444). Everything that reaches this catch has already lost its handoff — `callback` answers
+        // the paths that still know where the person wanted to go — so the destination here is a
+        // DECIDED one rather than a remembered one.
+        //
+        // ⚠️ `/tools` and not `/`: it is the only screen that reads `connectError` and turns it into a
+        // sentence (`portalAnswerOf`), and every code but the two about access lands on "the sign-in is
+        // broken" there — which is what happened. The root would take the reader somewhere that says
+        // nothing at all about the attempt they just made. Somebody who has no Intel session either is
+        // sent on to the login by the interface's own 401 handling, once, bounded by the sign-in loop
+        // guard (#118).
+        app.get("/auth/callback", async (context) => {
+            try {
+                return await browserAuth.callback(new URL(context.req.url), context.req.raw.headers);
+            }
+            catch (error) {
+                // ⚠️ The IntelError is logged here although `app.onError` deliberately does not log one:
+                // an expected refusal explains itself through its body, and this route no longer has a
+                // body. `oauth_session_invalid` is raised for two different situations — no readable
+                // handoff at all, and a Gate login handoff that ran out — and a deployment where EVERY
+                // callback fails (a rotated session key, a clock that drifted, a cookie the browser stopped
+                // sending) looks from the outside exactly like one person with a stale tab. Without this
+                // line nothing anywhere tells the two apart.
+                reportUnexpectedError(error);
+                const code = error instanceof IntelError ? error.code : "portal_sign_in_failed";
+                return context.redirect(`/tools?connectError=${encodeURIComponent(code)}`);
+            }
+        });
         app.post("/auth/logout", () => browserAuth.logout());
     }
     app.route("/api/v1", createHttp({

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

@@ -1,5 +1,6 @@
 import { TableMediaType } from "@anchrd/intel-contract/table";
 import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
+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";
 import { documentLinkTargets } from "./document-links/document-links.js";
@@ -10,6 +11,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,9 +1022,24 @@ export function createNodes(deps) {
                     return {
                         grant: replayed,
                         unreadable: await unreadableForPrincipal(actor, node.id, replayed.principal),
+                        unrunnable: nothingWithheld,
                     };
                 }
             }
+            /**
+             * ⚠️ Behind the replay and in front of `setGrant` — both halves matter (#442).
+             *
+             * In front of `setGrant` is the rule itself: nothing that could never work gets written, so
+             * no row, no idempotency key and no audit event. Every path that reaches the write passes
+             * here, including a replay whose grant was revoked in between and falls through.
+             *
+             * Behind the replay because otherwise this refusal would break the promise `IdempotencyKey`
+             * makes. A caller retries with the SAME key and the SAME body; if the retry arrives after the
+             * expiry the first attempt named, the value is no longer in the future — and the second call
+             * would be refused for a grant that is already written. The replay path writes nothing, so
+             * standing behind it costs the rule nothing and keeps the retry answering with what happened.
+             */
+            requireFutureExpiry(input.expiresAt, deps.now());
             const timestamp = deps.now().toISOString();
             const grant = await deps.repository.setGrant({
                 grant: {
@@ -1037,7 +1058,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/dist/shared/grant-expiry/grant-expiry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export declare function requireFutureExpiry(expiresAt: string | null, now: Date): void;

package/dist/shared/grant-expiry/grant-expiry.js

@@ -0,0 +1,26 @@
+import { IntelError } from "../intel-error/intel-error.js";
+/**
+ * ⚠️ A grant whose expiry has already passed is refused, never written (#442).
+ *
+ * It would otherwise be created, answered with a `201`, and listed — while reaching nobody. The
+ * sharer reads the row as done; the grantee gets no notification and finds out days later, if at
+ * all. That is the failure mode this repository keeps meeting: something that looks like success,
+ * and the only feedback is the wrong one.
+ *
+ * ⚠️ The check cannot live in the Zod schema. That boundary knows nothing about `deps.now()`, and
+ * the rule is decided by the very clock that evaluates the grant afterwards — so it belongs in the
+ * application layer, where every surface passes through it. The `.describe()` on `expiresAt`
+ * documents the rule; this refuses it.
+ *
+ * ⚠️ Equal to `now` is refused too: a grant that expires this instant is spent before the answer
+ * reaches the caller.
+ *
+ * `null` is untouched and stays what it always meant — a grant that does not expire on its own.
+ */
+export function requireFutureExpiry(expiresAt, now) {
+    if (expiresAt === null)
+        return;
+    if (Date.parse(expiresAt) > now.getTime())
+        return;
+    throw new IntelError(400, "grant_already_expired", "A grant's expiry has to lie in the future; pass null for one that does not expire on its own");
+}

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.23.0",
+  "version": "0.25.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,8 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.15.0",
-    "@anchrd/intel-contract": "^0.19.0",
+    "@anchrd/gate-sdk": "^0.19.0",
+    "@anchrd/intel-contract": "^0.21.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",