@procedures/client 0.0.0-stage → 0.2.0

package/dist/procedures/policy.js

@@ -0,0 +1,138 @@
+/**
+ * The call policy of a host: which nested calls a procedure can make (deep dive MCP-3).
+ *
+ * A host that serves procedures to an outside caller (the MCP server, a network server) gives an
+ * `expose` rule: the procedures that its callers can reach. A procedure can call other
+ * procedures through `ctx.client`. The policy decides for each nested call, with the immediate
+ * caller:
+ *
+ * - A data-driven caller (control flow, `runs-refs`, a procedure that `procedure.define` made)
+ *   runs refs that its caller chose. It can call only exposed procedures.
+ * - A code caller with `metadata.calls` can call the procedures that it declares, and the
+ *   exposed procedures.
+ * - A code caller without `calls` can call any procedure, unless the host sets `strictCalls`.
+ *   Then it can call only exposed procedures.
+ *
+ * Before, only the first rule existed. An exposed procedure of code could call any procedure, so
+ * a code procedure that turns its input into a call was a confused deputy. The declarations make
+ * the reach of each tool visible: a test of the MCP server pins it.
+ *
+ * A host without `expose` and without `strictCalls` (a library, the local CLI) checks nothing.
+ */
+import { pathToKey } from "./types.js";
+import { isDataDriven } from "./ref.js";
+/** True when a host has a policy: a nested call is examined only then. */
+export function hasCallPolicy(policy) {
+    return policy.expose !== undefined || policy.strictCalls === true;
+}
+/**
+ * True when one entry of `calls` allows a procedure key: the same key, or `"ns.*"` for a key
+ * that starts with `"ns."` (at any depth: `"fs.*"` allows `fs.read.json`).
+ */
+export function callMatches(entry, key) {
+    if (entry.endsWith(".*")) {
+        return key.startsWith(entry.slice(0, -1));
+    }
+    return entry === key;
+}
+/**
+ * This function checks the `calls` of a procedure's metadata and returns it, or undefined when
+ * there is none. It throws for an invalid list. `"*"` alone is refused: a procedure whose
+ * callees come from its input is data-driven and must have the `runs-refs` tag.
+ */
+export function validateCalls(calls, path) {
+    if (calls === undefined)
+        return undefined;
+    const where = pathToKey(path);
+    if (!Array.isArray(calls)) {
+        throw new TypeError(`metadata.calls of ${where} must be a list of procedure keys`);
+    }
+    for (const entry of calls) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new TypeError(`metadata.calls of ${where} has an entry that is not a procedure key: ${JSON.stringify(entry)}`);
+        }
+        if (entry === "*") {
+            throw new TypeError(`metadata.calls of ${where} is "*". A procedure whose callees come from its input is data-driven: ` +
+                `give it the "runs-refs" tag instead.`);
+        }
+        const body = entry.endsWith(".*") ? entry.slice(0, -2) : entry;
+        if (body.length === 0 || body.includes("*") || body.split(".").some((segment) => segment.length === 0)) {
+            throw new TypeError(`metadata.calls of ${where} has an invalid entry: "${entry}". Use "ns.name" or "ns.*".`);
+        }
+    }
+    return calls;
+}
+/** The `calls` of a procedure, or undefined when it declares none. */
+export function declaredCalls(procedure) {
+    return validateCalls(procedure.metadata?.calls, procedure.path);
+}
+/**
+ * The procedures that are not exposed, but that the exposed procedures can reach through their
+ * `metadata.calls`, also through more than one step. A data-driven procedure reaches only
+ * exposed procedures, and under `strictCalls` a procedure without `calls` does too, so neither
+ * adds an edge. The edges are sorted. A test of the MCP server pins them.
+ */
+export function hiddenReach(procedures, expose) {
+    const byKey = new Map(procedures.filter((procedure) => procedure.handler).map((procedure) => [pathToKey(procedure.path), procedure]));
+    const edges = new Map();
+    const visited = new Set();
+    const visit = (procedure) => {
+        const from = pathToKey(procedure.path);
+        if (visited.has(from))
+            return;
+        visited.add(from);
+        if (isDataDriven(procedure))
+            return;
+        for (const entry of declaredCalls(procedure) ?? []) {
+            for (const [key, callee] of byKey) {
+                if (!callMatches(entry, key) || expose(callee.path))
+                    continue;
+                edges.set(`${from} -> ${key}`, { from, to: key });
+                visit(callee);
+            }
+        }
+    };
+    for (const procedure of byKey.values()) {
+        if (expose(procedure.path))
+            visit(procedure);
+    }
+    return [...edges.keys()].sort().map((key) => edges.get(key));
+}
+/**
+ * The refusal of a nested call from `caller` to `path` under `policy`, or undefined when the
+ * call is allowed.
+ */
+export function nestedCallRefusal(caller, path, policy) {
+    if (!hasCallPolicy(policy))
+        return undefined;
+    const exposed = policy.expose ? policy.expose(path) : true;
+    const key = pathToKey(path);
+    const from = pathToKey(caller.path);
+    if (isDataDriven(caller)) {
+        return exposed
+            ? undefined
+            : {
+                code: "NOT_EXPOSED",
+                message: `Procedure not exposed: ${key}. ${from} runs procedure refs from its input, so it can call only ` +
+                    `the procedures that this server exposes.`,
+            };
+    }
+    const calls = declaredCalls(caller);
+    if (calls !== undefined) {
+        if (exposed || calls.some((entry) => callMatches(entry, key)))
+            return undefined;
+        return {
+            code: "NOT_DECLARED",
+            message: `Procedure not declared: ${from} calls ${key}, but its metadata.calls does not name it.`,
+        };
+    }
+    if (policy.strictCalls && !exposed) {
+        return {
+            code: "NOT_EXPOSED",
+            message: `Procedure not exposed: ${key}. ${from} declares no metadata.calls, and this server lets such a ` +
+                `procedure call only the procedures that it exposes.`,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=policy.js.map

package/dist/procedures/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/procedures/policy.ts"],"names":[],"mappings":"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"}