@anchrd/intel-api 0.31.0 → 0.32.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -9,6 +9,7 @@ import { createFlows } from "../../flows/flows.js";
 import { createIndexing, PermanentIndexingError } from "../../indexing/indexing.js";
 import { createIntel } from "../../intel/intel.js";
 import { createNodes } from "../../nodes/nodes.js";
+import { bearer } from "../../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../../shared/intel-error/intel-error.js";
 import { sha256Hex } from "../../shared/sha256/sha256.js";
 import { createTools } from "../../tools/tools.js";
@@ -256,7 +257,49 @@ export default {
             flows,
             tools,
             audit: createAudit({ audit: auditRepository }),
-            boards: createBoards({ boards: boardRepository, nodes, now }),
+            boards: createBoards({
+                boards: boardRepository,
+                nodes,
+                now,
+                /**
+                 * The seam to gate's directory (#700, D70).
+                 *
+                 * ⚠️ BUILT HERE AND NOWHERE ELSE, because this is the only place that legitimately holds
+                 * the caller's bearer. `Actor` carries the resolved identity, never the credential that
+                 * produced it, and the board service must stay that way: it narrows what gate offers, it
+                 * does not get to speak for anybody.
+                 *
+                 * ⚠️ The token is resolved LAZILY and at most once. Two doors lead in and they answer
+                 * differently — `/mcp` and the API carry an `Authorization` header, the browser carries a
+                 * cookie the session has to be asked about — and doing that work eagerly would cost a
+                 * session read on every request that never opens a picker.
+                 *
+                 * ⚠️ No token means an EMPTY answer, never a throw. A picker with no names shows nothing;
+                 * a board that refuses to load because gate was slow is the worse outcome, and it would
+                 * take the whole screen with it.
+                 */
+                directory: (() => {
+                    let pending = null;
+                    const token = () => {
+                        pending ??= (async () => bearer(request.headers) ?? (await auth.resolve(request.headers))?.bearer ?? null)();
+                        return pending;
+                    };
+                    return {
+                        async search(query) {
+                            const value = await token();
+                            if (!value)
+                                return [];
+                            return await gate.directory.search(value, { q: query });
+                        },
+                        async resolve(ids) {
+                            const value = await token();
+                            if (!value)
+                                return [];
+                            return await gate.directory.resolve(value, { ids });
+                        },
+                    };
+                })(),
+            }),
             bundle: createBundle({
                 repository: nodeRepository,
                 flows: flowRepository,

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

@@ -1,5 +1,5 @@
 import { ARCHIVE_COLUMN_ID, BoardColumn } from "@anchrd/intel-contract/board";
-import { subtreeBindings, subtreeCte } from "./db-grants.js";
+import { grantInForce, subtreeBindings, subtreeCte } from "./db-grants.js";
 function parseList(raw, of) {
     // The column is `NOT NULL DEFAULT '[]'`, but it is JSON written by this repository and read back
     // by it — a value that cannot be parsed is a defect, not a caller's mistake. It must still not
@@ -235,5 +235,63 @@ export function createBoardRepository(deps) {
             // needing fractions immediately.
             return (row?.top ?? 0) + 1;
         },
+        /**
+         * Who reaches this board once inheritance is resolved (#700, D70).
+         *
+         * ⚠️ ONE statement, hence one D1 snapshot, for the reason `listEffectiveAccess` gives at the
+         * node repository: two parallel SELECTs are not atomic, and a grant mutation between their
+         * snapshots produces a set of people that never existed as a whole.
+         *
+         * ⚠️ It answers the THREE things the caller needs, not a list of grants. A service that
+         * received grant rows here would be one careless `return` away from handing a board's
+         * membership to anyone who can read it; what leaves this method cannot be turned back into who
+         * granted what to whom.
+         *
+         * ⚠️ `verb = 'read'`, and that is not a detail. The verbs here are granted INDEPENDENTLY
+         * (ADR-0004 §2): `write` does not follow from `read` and `read` does not follow from `write`.
+         * Counting any verb would offer somebody who holds only `write` or `share` as an assignee for a
+         * board they cannot open — the exact opposite of what D70 decided, arrived at by asking a
+         * slightly different question than `columnsOrRefuse` asks two lines earlier.
+         *
+         * ⚠️ `UNION`, never `UNION ALL`: a ring in `parent_id` has to end the recursion rather than the
+         * database, the same reason every other walk of this tree gives.
+         */
+        async effectiveAccess(boardId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT id, parent_id, owner_id FROM nodes WHERE 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 ancestors WHERE owner_id IS NOT NULL))
+              AS owner_ids_json,
+            (SELECT json_group_array(principal_id)
+             FROM (
+               SELECT DISTINCT grant_row.principal_id
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE grant_row.principal_type = 'user'
+                 AND grant_row.principal_id IS NOT NULL
+                 AND grant_row.verb = 'read'
+                 AND ${grantInForce}
+             )) AS principal_ids_json,
+            (SELECT COUNT(*)
+             FROM node_grants grant_row
+             JOIN ancestors ON ancestors.id = grant_row.node_id
+             WHERE grant_row.principal_type = 'organization'
+               AND grant_row.verb = 'read'
+               AND ${grantInForce}) AS organization_grants`)
+                .bind(boardId, deps.now().toISOString(), deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                principalIds: JSON.parse(row?.principal_ids_json ?? "[]"),
+                organizationWide: (row?.organization_grants ?? 0) > 0,
+            };
+        },
     };
 }

package/dist/boards/boards.js

@@ -20,6 +20,10 @@ export const DEFAULT_COLUMNS = [
 // than the literal `"todo"` in three places: the fallback exists FOR the unconfigured board, so a
 // copy of it would drift exactly where it is the only thing deciding.
 export const FIRST_DEFAULT_COLUMN = DEFAULT_COLUMNS[0].id;
+// Below this a query answers empty rather than with everybody. A single letter is not a search, it
+// is a listing under a different name — the same floor gate holds at its own door, stated here so
+// this surface keeps its own promise (#700).
+const MINIMUM_QUERY = 2;
 export function createBoards(deps) {
     /**
      * ⚠️ The one place "which board, and may this actor DO THIS to it" is answered — and the verb is
@@ -284,5 +288,60 @@ export function createBoards(deps) {
             }
             return await viewOrRefuse(actor, { boardId: row.boardId, includeArchived: false });
         },
+        /**
+         * Who this card may be given to (D70, #700).
+         *
+         * ⚠️ THE ANSWER IS NARROWER THAN GATE'S, NEVER WIDER. gate is asked first and its hits are then
+         * dropped down to the people who can actually open this board. That order is what makes the
+         * door safe to offer to anyone who can read the board: whatever survives the filter, gate would
+         * have handed the same person anyway at its own `POST /directory/search`.
+         *
+         * The reverse order would have been the leak: asking the board first and then naming the
+         * principals would hand out a membership list for a board to anyone who can see it.
+         */
+        async searchAssignees(actor, input) {
+            // `read`, not `share`: offering an assignee is something everyone who can open the board
+            // does, while managing grants is not. The 404 from here is the same one every other board
+            // read gives, so a board one may not see stays indistinguishable from one that is not there.
+            await columnsOrRefuse(actor, input.boardId, "read");
+            if (!deps.directory)
+                return { items: [] };
+            /**
+             * ⚠️ ENFORCED HERE, not only described. The contract's `query` says a single character
+             * answers empty, and until this line that sentence was true only because gate happens to
+             * hold the same floor — a promise this repository made and a different service kept.
+             *
+             * It is also the cheaper answer: a letter that can only ever produce a listing does not
+             * need to travel to gate first to be refused there.
+             */
+            if (input.query.trim().length < MINIMUM_QUERY)
+                return { items: [] };
+            const hits = await deps.directory.search(input.query);
+            if (hits.length === 0)
+                return { items: [] };
+            const access = await deps.boards.effectiveAccess(input.boardId);
+            // A grant to the organization means everybody reaches the board, so there is nothing left to
+            // narrow — and narrowing anyway would produce an empty picker on exactly the boards that are
+            // shared with everyone, which is most of them.
+            if (access.organizationWide)
+                return { items: hits };
+            const reaches = new Set([...access.ownerIds, ...access.principalIds]);
+            return { items: hits.filter((hit) => reaches.has(hit.id)) };
+        },
+        /**
+         * What the people already recorded on cards are called (#258, #700).
+         *
+         * ⚠️ NOT narrowed by the board, and that is the difference from the search above. Someone whose
+         * grant was withdrawn, or whose account was switched off, is still the person this card was
+         * given to. Filtering them out would leave the card reading as unassigned, which is a worse
+         * answer than the truth — and it would not protect anything, because the caller already holds
+         * the id and got it from a card they may read.
+         */
+        async resolveAssignees(actor, input) {
+            void actor;
+            if (!deps.directory)
+                return { items: [] };
+            return { items: await deps.directory.resolve(input.ids) };
+        },
     };
 }

package/dist/boards/boards.types.d.ts

@@ -1,4 +1,4 @@
-import type { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, BoardView } from "@anchrd/intel-contract/board";
+import type { BoardAssignee, BoardAssigneeResolveInput, BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, BoardView } from "@anchrd/intel-contract/board";
 import type { Node } from "@anchrd/intel-contract/node";
 import type { Actor } from "../nodes/nodes.types.js";
 export type { BoardView };
@@ -42,6 +42,33 @@ export interface BoardRepository {
     taskRow(actor: Actor, taskId: string, verb: "read" | "write"): Promise<BoardTaskRow | null>;
     updateTask(taskId: string, fields: Record<string, string | number | null>, occurredAt: string): Promise<void>;
     nextPosition(boardId: string, status: string): Promise<number>;
+    /**
+     * Who reaches this node once inheritance is resolved: every grant along the folders above plus
+     * the owners. The same answer `listEffectiveAccess` gives, reached through the SAME repository
+     * method, so the two can never disagree about who has access.
+     *
+     * ⚠️ Read here WITHOUT the `share` permission the application-level `listEffectiveAccess`
+     * demands, and that is deliberate rather than an oversight. The two callers ask for different
+     * reasons: managing sharing is an owner's job, while naming the people a card may be given to is
+     * something anyone who can open the board has to be able to do. The answer never leaves this
+     * service as a list of grants; it is only ever used to NARROW what gate already offers.
+     */
+    effectiveAccess(boardId: string): Promise<{
+        ownerIds: string[];
+        principalIds: string[];
+        organizationWide: boolean;
+    }>;
+}
+/**
+ * The one seam to gate's directory, built PER REQUEST around the caller's bearer.
+ *
+ * ⚠️ The bearer never reaches this service, and it must not: `Actor` is the resolved identity, not
+ * the credential that produced it. The edge already holds the token because it just authorized with
+ * it, so it closes over it here and hands in something that answers questions instead.
+ */
+export interface BoardDirectoryPort {
+    search(query: string): Promise<BoardAssignee[]>;
+    resolve(ids: string[]): Promise<BoardAssignee[]>;
 }
 export interface BoardNodePort {
     create(actor: Actor, input: {
@@ -67,10 +94,17 @@ export interface BoardDeps {
     boards: BoardRepository;
     nodes: BoardNodePort;
     now(): Date;
+    directory?: BoardDirectoryPort;
 }
 export interface BoardService {
     get(actor: Actor, input: BoardGetInput): Promise<BoardView>;
     update(actor: Actor, input: BoardUpdateInput): Promise<BoardView>;
     createTask(actor: Actor, input: BoardTaskCreateInput): Promise<BoardView>;
     updateTask(actor: Actor, input: BoardTaskUpdateInput): Promise<BoardView>;
+    searchAssignees(actor: Actor, input: BoardAssigneeSearchInput): Promise<{
+        items: BoardAssignee[];
+    }>;
+    resolveAssignees(actor: Actor, input: BoardAssigneeResolveInput): Promise<{
+        items: BoardAssignee[];
+    }>;
 }

package/dist/http/http.js

@@ -1,5 +1,5 @@
 import { AuditListRequest } from "@anchrd/intel-contract/audit";
-import { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
+import { BoardAssigneeResolveInput, BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
 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";
@@ -245,6 +245,34 @@ export function createHttp(deps) {
         });
         return context.json(await deps.boards.get(asActor(auth), input));
     });
+    /**
+     * Who this card may be given to (#700, D70).
+     *
+     * ⚠️ `nodes/read`, not a capability of its own and certainly not `nodes/write`. Offering an
+     * assignee is something everyone who can open the board does; a separate permission would be one
+     * more thing to grant before a picker works, and nothing would be safer for it — the answer is
+     * already narrower than what gate hands any signed-in person at its own door.
+     */
+    app.get("/boards/:boardId/assignees", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = BoardAssigneeSearchInput.parse({
+            boardId: context.req.param("boardId"),
+            query: context.req.query("q") ?? "",
+        });
+        return context.json(await deps.boards.searchAssignees(asActor(auth), input));
+    });
+    /**
+     * What the people already on cards are called (#258, #700).
+     *
+     * ⚠️ A POST although it reads, and for the same reason gate's own door is one: the ids travel in
+     * the body. A list of a hundred identifiers in a query string lands in proxy logs and in browser
+     * history, and it would hit the length limit long before the hundredth.
+     */
+    app.post("/boards/assignees/resolve", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const input = BoardAssigneeResolveInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.boards.resolveAssignees(asActor(auth), input));
+    });
     app.patch("/boards/:boardId", async (context) => {
         const auth = requireCapability(context, "nodes", "write");
         const input = BoardUpdateInput.parse(await context.req.json().catch(() => null));

package/dist/mcp/mcp.js

@@ -1,6 +1,6 @@
 import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
 import { AuditListRequest } from "@anchrd/intel-contract/audit";
-import { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
+import { BoardAssigneeResolveInput, BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
 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";
@@ -180,6 +180,41 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.boards.get(actor, input)));
+        // ⚠️ Two tools rather than one, because they answer two questions that differ in exactly one
+        // way: `board_assignee_list` offers whom a card MAY be given to and is narrowed to this board
+        // (D70); `board_assignee_resolve` names people who are ALREADY on cards and is not narrowed,
+        // because somebody whose access was withdrawn is still who the card belongs to.
+        //
+        // ⚠️ `list`, NOT `search`, although a query narrows it. `search` is the ONE bare verb at the
+        // root of this surface (Jack's decision 2026-08-09, `packages/api/CLAUDE.md`), and a second one
+        // behind a domain would make that exception look like a pattern. The verb for "reads many" is
+        // `list`, and a filter does not change which verb a call is.
+        server.registerTool("board_assignee_list", {
+            title: "Who a card on this board can be given to",
+            description: "Find the people you may set as assignee on a card of this board, by typing part of a name or an address. Only people who can actually open THIS board are offered, so the same query against two boards can give two different answers. Under two characters the answer is empty rather than everybody. Use board_assignee_resolve to name somebody already on a card.",
+            inputSchema: BoardAssigneeSearchInput,
+            annotations: {
+                title: "Who a card on this board can be given to",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                // ⚠️ The answer comes from gate, not from this database, and it changes when an account
+                // or a grant does. `false` would promise a stability nothing here controls.
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.boards.searchAssignees(actor, input)));
+        server.registerTool("board_assignee_resolve", {
+            title: "What the people on these cards are called",
+            description: "Turn assignee ids into names, so a card can say who it belongs to instead of showing an identifier. Ids that cannot be named are absent from the answer rather than reported as missing. Not narrowed to a board: somebody whose access was withdrawn is still who the card belongs to.",
+            inputSchema: BoardAssigneeResolveInput,
+            annotations: {
+                title: "What the people on these cards are called",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.boards.resolveAssignees(actor, input)));
         server.registerTool("board_task_create", {
             title: "Add a card to a board",
             description: "File a new card on a board. Omit the status to put it in the first column. Name a parent task to make it a subtask — it lands on the same board, and moving an existing card under another one is `node_update` with a new parent. The card is a node like any other: its own address, its own permissions, its own history.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,8 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.24.0",
-    "@anchrd/intel-contract": "^0.24.0",
+    "@anchrd/gate-sdk": "^0.25.0",
+    "@anchrd/intel-contract": "^0.25.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",